;-------------------------------------------------------------------------------
;
;   ;----------------------------------------------;
;   ;     BlitsBazic Full Foundation Tutorial      ;
;   ;            More than pure logic!             ;
;   ;  Created by TheChance (TheChange@yahoo.com)  ;
;   ;----------------------------------------------;
;   ; First edition - Private edition (QB1)        ;
;   ;   For ID in 1997                             ;
;   ; Second edition - Private edition (BB1)       ;
;   ;   For Wizzy (f.k.a. Hotshot) in 2003         ;
;   ; Third edition - Public edition (BB2)         ;
;   ;   Full Foundation (Revision 2)               ;
;   ;,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,;
;
;,,,,
    ;   Introduction
;----
;
;   This tutorial teaches you
;   the basics of (game) programming
;   under BlitzBasic(tm).
;
;   You do not need to know much at all
;   to follow this tutorial really.
;   A little bit of knowledge
;   about basic maths and algebra
;   can be helpful though.
;
;   But above all, logical thinking :)
;   So go at it one step at a time.
;
;   I've tried to keep the number of
;   difficult words to a minimum.
;   So hopefully you won't need
;   a dictionary too often :o)
;
;   If something is unclear,
;   try to read on a little further,
;   the answer you're looking for
;   should not be too far away.
;
;   The tutorial is made up of multiple parts,
;   starting with the building blocks
;   of basic programming and slowly
;   leading towards the game world.
;
;   Try to read the tutorial in order.
;   Jumping towards the end at one time
;   can be very confusing.
;
;   You should try to get to know
;   the Blitz Basic program
;   before you begin with the tutorial.
;
;   Here's basically how it works:
;
;   You can use Blitz to write programs.
;   You create the source code
;   of these programs inside Blitz.
;
;                            +------------------+
;        .---------.         | +------------------+
;       /           \        | |                  |
;       |   Blitz   | <----> | |   Source code    |
;       \           /        +-|                  |
;        `---------'           +------------------+
;
;            /|\
;             | 
;             |       /^\
;            \|/      \_/
;                  --__|__--
;       Programmer     |
;                     / \
;                    /   \
;
;   Then you can also use Blitz
;   to convert the source code
;   to a program that stands on its own.
;
;     +------------------+
;     | +------------------+         .---------.          .----------.
;     | |                  |        /           \        /            \
;     | |   Source code    | -----> |   Blitz   | -----> |  Program   |
;     +-|                  |        \           /        \            /
;       +------------------+         `---------'          `----------'
;
;   The code in a Blitz Basic file,
;   (For example "Filename.BB")
;   containing the source code,
;   is read from top to bottom.
;
;   And you can edit a number of
;   Blitz Basic files at once.
;
;   You can run the program
;   you are currently editing
;   using the Run toolbar button,
;   the Run option from the pull-down menu,
;   or simply by pressing F5 on the keyboard.
;
;   From the same pull-down menu (Program)
;   there's an option to enable Debug mode.
;
;   When Debug mode is Enabled
;   Blitz will try to protect
;   Windows from any harm
;   your program may cause.
;
;   Blitz will also inform you
;   with very specific information
;   if anything goes wrong.
;
;   So please keep Debug mode
;   turned on, for now ;)
;
;   Here you'll find a short overview
;   of each part contained in the tutorial:
;
;       Part 1 - Introduction To Variables
;
;           Guiding you through the first steps of programming
;           using a special storyline.
;
;       Part 2 - Single Basic Variables
;
;           What variables really are and how they work.
;
;       Part 3 - Conditions
;
;           What more you can do with variables,
;           such as comparing them.
;
;       Part 4 - Loops
;
;           Various ways of repetition can make a
;           programmer's life a lot easier.
;
;       Part 5 - Variable Collections
;
;           Welcome to the worlds of memory control.
;
;       Part 6 - Routines
;
;           Separating a program in constructive blocks.
;
;       Part 7 - Game On
;
;           The basic construction of a game.
;
;   Each part contains a number of sections,
;   separated by special separator lines,
;   and contains code you can run to try it out.
;
;   As some sections are quite large,
;   I would recommend copying and pasting
;   the section you are reading
;   to a new program and running it from there.
;
;   If you have any questions, or if something is unclear,
;   please email me at: TheChance (TheChange@yahoo.com).
;
;,,,,
    ;
;----
;
;   ;-------------------------------;
;   ;   Introduction To Variables   ;
;   ;,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,;
;
;
;   This first part can be run in one go.
;   So no need for copying or pasting.
;
;-------------------------------------------------------------------------------
;
;   A variable is a lot like a person with a number of coins.
;   Suppose Charlie, Melany, Edwin and Richie join us.
;   I'll show you how many coins everyone has.

Charlie =     2                         ; Charlie has 2 coins.
Melany  =     3                         ; Melany has 3 coins.
Edwin   =     6                         ; Edwin has 6 coins.
Richie  = 30000                         ; Richie has 30000 coins.

;   Now it's time to say hello to the audience,
;   e.g. the people running the program :)

Print "Hi there!"                       ; The command Print prints something on
                                        ; the screen at current (invisible)
                                        ; cursor location and moves the cursor
                                        ; to the beginning of the next line.
Print                                   ; Entering nothing behind Print will
                                        ; result in the (invisible) cursor
                                        ; simply going to the (beginning of the)
                                        ; next line.

;-------------------------------------------------------------------------------
;
;   Linda joins us.
;   Melany likes her so much that she gives Linda all of her coins.

Linda  = Melany                         ; Linda matches Melany.
Melany = 0                              ; Melany has 0 coins.

;-------------------------------------------------------------------------------
;
;   Another person joins us: Susan.
;   Charlie and Edwin are not so fond of her.
;       - Why?
;   Because she steals not only all of Charlie's coins
;   but also all of Edwin's :P

Susan   = Charlie + Edwin               ; Susan matches the sum of Charlie and
                                        ; Edwin.
Charlie = 0                             ; Charlie has 0 coins.
Edwin   = 0                             ; Edwin has 0 coins.

;   We can also use Print to see how many coins someone has.

Print "(1)"                             ; To keep track of which section this
Print                                   ; is.
Print "Charlie has "+Charlie+" coins."  ; The `+` sign here is used as glue,
Print "Melany  has "+Melany +" coins."  ; so if you have a person that doesn't
Print "Edwin   has "+Edwin  +" coins."  ; stick, just use some glue. One drop
Print "Richie  has "+Richie +" coins."  ; should be enough :)
Print "Linda   has "+Linda  +" coins."  ; Example:
Print "Susan   has "+Susan  +" coins."  ;   PRINT "text 1" + Person + "text 2"
Print

;   Note that there are several types of glue.
;   We will call this one text-glue.
;
;-------------------------------------------------------------------------------
;
;   Richie is very wealthy (remember he has 30000 coins!).
;   Therefore he wants to borrow Edwin half of his coins.

Lone = Richie / 2                       ; Lone is not a person ofcourse but can
                                        ; be treated as one since we consider
                                        ; variables to be persons.
Edwin = Edwin + Lone                    ; Edwin is himself plus Lone.
                                        ; This is the unique way to add numbers
                                        ; to a person.
Richie = Richie / 2                     ; Richie is half of himself OR
                                        ; Richie is himself divided by 2.

;-------------------------------------------------------------------------------
;
;   Lets gamble!
;   Everyone who has coins joins the party.
;   Everyone puts half of their coins into the pot.

Pot = Edwin / 2 + Richie / 2 + Linda / 2 + Susan / 2
                                        ; Just like in maths.
Edwin  = Edwin  / 2                     ; Edwin is half of himself.
Richie = Richie / 2                     ; Richie is half of himself.
Linda  = Linda  / 2                     ; Linda is half of herself.
Susan  = Susan  / 2                     ; And Susan is half of herself.

;   Don't say it, we'll just treat Pot as a person.
;   Okay, now, suppose Edwin wins the pot.

Edwin = Edwin + Pot                     ; Edwin is himself plus the pot (Pot).
Pot   = 0                               ; Pot becomes empty.

;   Edwin has got coins again.
;   Now he can pay back his lone to Richie.

Edwin  = Edwin  - Lone                  ; Edwin is himself minus Lone.
Richie = Richie + Lone                  ; Richie is himself plus Lone.
Lone   = 0                              ; No more lone.

;   Let's check out how many coins everyone has now.

Print "(2)"
Print
Print "Charlie = "+Charlie              ; Charlie's coins.
Print "Melany  = "+Melany               ; Melany's coins.
Print "Edwin   = "+Edwin                ; Edwin's coins.
Print "Richie  = "+Richie               ; Richie's coins.
Print "Linda   = "+Linda                ; Linda's coins.
Print "Susan   = "+Susan                ; Susan's coins.
Print

WaitKey                                 ; Stops the program until you press
                                        ; the ANY key.. err.. any key :)

;-------------------------------------------------------------------------------
;
;   You may be wondering how someone with 3 coins
;   can give away half of his or her coins.
;   Well, apart from the fact that we are using chocolate coins,
;   when using Integer values, like we are now,
;   you can only store natural numbers (whole numbers)
;   so all half coins will be eaten by hungry coin owners
;   (e.g. all coin owners) :P
;
;   For example, if Melany would find 3 coins somewhere...

Melany = Melany + 3                     ; Melany is herself plus 3

;   And because Charlie has no coins,
;   she would share half of her coins with him...

Charlie = Melany / 2                    ; Charlie is himself plus half of
                                        ; Melany's coins.
Melany  = Melany / 2                    ; Melany is half of her own coins.

;   Now if we take a look to see how many coins they have...

Print "(3)"
Print
Print "Charlie: "+Charlie
Print "Melany:  "+Melany
Print

;   You can see they both have 1 coin.. so they both ate half a coin.
;   You have no idea how hungry these people are! :)
;
;-------------------------------------------------------------------------------
;
;   Charlie on the other hand gets extremely hungry
;   and cannot stand it any longer.
;   So he takes a number of coins from Edwin,
;   43 coins to be exact.

Number  = 43                            ; Number of coins is 43.
Edwin   = Edwin   - Number              ; Edwin is himself minus 43.
Charlie = Charlie + Number              ; Charlie is himself plus 43.

;   Now he will try to eat them all.
;   But after 41 chocolate coins,
;   he can't eat anymore.
;   Not surprisingly :)

Eat     = Number  - 2                   ; 41 coins to be eaten.
Charlie = Charlie - Eat                 ; Charlie is himself minus 41.

;   The other two coins he couldn't eat
;   he throws away.

Number = 0                              ; No more coins to eat.
Eat    = 0                              ; So we're done eating.

;   Let us look at the results (again).
;   You can probably guess how many coins everyone has.

Print "(4)"
Print
Print "Charlie = "+Charlie
Print "Melany  = "+Melany
Print "Edwin   = "+Edwin
Print "Richie  = "+Richie
Print "Linda   = "+Linda
Print "Susan   = "+Susan
Print

;-------------------------------------------------------------------------------
;
;   There's a genius in our midst! She is a scientist.
;       - Who is she?!
;   Well, just Melany...
;   She invented a coin-multiplication machine!
;   This machine has a maximum multiplication factor of 8.
;   This means you can multiply by 8 at the maximum.
;       - But why does Melany need a CMM (coin-multiplication machine) ?
;   Because she has a deal with Linda, her best friend.
;   Linda gives her a coin to be multiplied by 8.
;   After this they share the 8 coins so that's 4 each.
;
;   Linda puts her last coin into Melany's machine
;   and Melany hits the 'Multiply' button.

Machine = Machine + 1                   ; Machine contains 1 coin.
Linda   = Linda   - 1                   ; Linda has no more coins.
Machine = Machine * 8                   ; Machine is itself, multiplied by 8.

;   Multiplication succesful!
;   Now share the profit.

Linda   = Linda  + Machine / 2          ; Linda gets half of Machine.
Melany  = Melany + Machine / 2          ; Melany also gets half of Machine.
Machine = 0                             ; Machine is now empty.

;-------------------------------------------------------------------------------
;
;   Susan feels sad because both Melany and Linda
;   have the same amount of coins she has.
;   So she decides to steal the CMM (coin-multiplication machine)
;   and use a rate of 16 instead of 8.
;       - That's not possible! There's a maximum of 8.
;   Yes.
;   You know, I know, Melany and Linda know.
;   But Susan doesn't know!
;       - So what happens next?
;   So she sets the multiplication factor to 16 and presses MULTIPLY.
;   The machine's starting to make all kinds of weird noises.
;   And BOOM!
;   The machine explodes and Susan gets killed.

Deceased = -1                           ; Deceased equals -1 coins.
Susan    = Deceased                     ; Susan has deceased.

;   Okay in our case it is not, like,
;   having less than 0 bucks on a bank-acount.
;   But in our case we call it a 'type-of-life' so to speak.
;   So long as a person has more than or equal to 0 coins, he/she is alive.
;   When the number of coins is below 0,
;   we could say that the person is in a different 'state-of-life'.
;   For example, when deceased, the person has a value of -1.
;   But there could also be other (negative) values, such as:

Haunting =  -2                          ; Person could be haunting the place.
Oblivion = -20                          ; Person has deceased but doesn't know
                                        ; it (yet).
Tired = -100                            ; Person is tired of life.
Alive =    0                            ; When being born, a person is alive.

;   So you could have all kinds of states to be in. For example if Edwin
;   suddenly gets tired of life, but he was sensible and stored his coins in
;   a safe.

Safe  = Edwin                           ; Safe contains Edwin's coins.
Edwin = Tired                           ; Edwin is now tired of life.

;-------------------------------------------------------------------------------
;
;   Melany is not really satisfied with her coins,
;   something to do with brand or something.
;   She looks at Charlie's and asks him if he would like to trade coins.
;   Ofcourse, having less coins than her, he cannot refuse.

Trade   = Charlie                       ; Melany ----------> Charlie
Charlie = Melany                        ;   /|\       2         |
Melany  = Trade                         ;    |                  |
                                        ;    +----- Trade <-----+
                                        ;      3              1

Trade = 0                               ; Done trading.

;   Also Edwin, the smart-ass, being tired and all,
;   would like to trade coins with Richie, in this case.
;   Richie is smart and refuses.
;   Instead he offers Edwin 18 coins.
;   Now Richie remains the richest.

Gift   = 18                             ; A gift from Richie.
Richie = Richie - Gift                  ; Richie gets rid of 18 coins.
Edwin  = Safe                           ; Edwin stops being tired of life, and
                                        ; retrieves his coins from the safe.
Edwin  = Edwin  + Gift                  ; Edwin gains 18 coins.

Gift = 0                                ; The gift was given.
Safe = 0                                ; Don't forget to empty the safe.
                                        ; It's not a magic safe! :P

;   Let's look at the end-results,
;   as insignificant as they may be.

Print "(5)"
Print
Print "Charlie has "+Charlie+" coins left."
Print "Melany  has "+Melany +" coins left."
Print "Edwin   has "+Edwin  +" coins left."
Print "Richie  has "+Richie +" coins left."
Print "Linda   has "+Linda  +" coins left."
Print "Susan   has "+Susan  +" coins left."

WaitKey                                 ; Waiting for you to press a key.
End                                     ; Ends the program instantly.

;-------------------------------------------------------------------------------
;
;   Now, I believe you know a lot about persons :)
;   So let the following definition fly through your mind:
;
;       Variables = Persons
;
;   Get the picture?
;   From now on, persons are considered to be variables.
;   And that's all there is to it :P
;
;-------------------------------------------------------------------------------