                        ANTS THE EXDOUS Version 1.0
                            By Michael Hughes
                         mhsoft_online@yahoo.com
                     www.geocities.com/mhsoft_online
                     -------------------------------
                              SOURCE CODE
                             DOCUMENTATION
                     -------------------------------

CONTENTS
--------

1) Introductions
2) Program Overview
3) Initialising
4) The INTRO menu system
5) Gameplay
6) MIDI
7) File Formats

1) INTRODUCTION
---------------

This is the programmers documentation that accompanies the source code for
Ants:The Exodus v1.0 (Ants TE). It is intended for use by QBasic programmers only. If
you have no programming knowledge and want to simply play the game, ignore
this file and all files with the .BAS extension.

If you are missing any files, the program can be downloaded in its entirity
from http://www.geocities.com/mhsoft_online.

This documentation assumes that you have played the game and so are familiar
with the basic concepts. Otherwise you should read the README.TXT file that
accompanies the game. 

This is only a brief documentation to make up for the less than liberal use 
of comments in the source code. It explains the overall structure of the
game, not what individual lines do. Experienced programmers will be able to
work that out for themselves.

This file documents the following:

INTRO.BAS    : The 1st Main module for Ants.
LEVEL.BAS    : The 2nd Main module for Ants
ANTS.BAT     : The startup batch file for the game
NOSOUND.BAT  : The startup batch file for the game -> disables sound
SETSOUND.BAT : The startup batch file for sound setup

It also explains the format used in .SPRs , .MAPs and .SAVs.

The SETSOUND and MAPMAKER utilities are not documented.

Please note the folowing:
1) I will refer to INTRO.BAS and LEVEL.BAS throughout this documentation.
   When compiled these will obviously be INTRO.EXE and LEVEL.EXE
2) From the game-players point of view, the 'Exodus' is when, at the end of
   the game, the princesses become free. However, in the source and doc,
   'exodus' refers to the time when they are released from a start square.
   This problem arose from the fact that I made up the story after writing
   the game and saw no point in going back to change things.
3) This document uses British spellings for words such as colour (USA color).
   However, since QBasic is an American program commands such as COLOR
   and RANDOMIZE are spelt in the US fashion. I will avoid confusion by
   putting normal words in lower case and QB commands in CAPITALS.
4) Ants TE uses the CHAIN command to pass control between modules. For reasons
   known best to itself, QBasic requires the program to be compiled with
   the option "requires BRUN45.EXE" for information to be passed between 
   modules, so if you recompile make sure you chose this option.
5) I'm sorry if there are any errors in this documentation. I am writing it
   just before I upload Ants TE in June and, considering I wrote much of the
   heavy-duty code in February, I think I can be excused the odd mistake.


If you have any comments or suggestions, don't hesitate to contact me at
mhsoft_online@yahoo.com.

2) PROGRAM OVERVIEW
-------------------

The following chart shows how control passes between modules and sub-routines.
This is by no means exhaustive, many sub-routines have been left out. A good
example is the MIDI sub-routines, these are constantly called from many other
routines.

 ANTS.BAT or NOSOUND.BAT
 --> INTRO.BAS
     <--> InitMain
     <--> InitObjects                             
     <--> InitSprites                             
     <--> DoFront                                 
     <--> DoMainMenu
          If NEW GAME/ADDON selected           If LOAD GAME selected          
          <--> DoMission (NG only)	        	
              CHAIN 
              ------> LEVEL.BAS   		LEVEL.BAS
                      <--> DoLevel		<--> DoLoadGame
                           <--> InitWorld              |
                           <--> DrawWorld   <----------
                                <--> DrawPlace
                                     <--> DrawObject
                      <--> DoGame
                           <--> DoTick
                              <--> DoHideSprite
                                   <--> DrawPlace
                                        <--> DrawObject
                              <--> DoMovesprite
                                   <--> DoFree
                              <--> DoCheck
                              <--> DoDrawSprite
                         <--> DoInMenu
                         <--> DoSave
                              <--> DoSaveGame
                         <--> DoExodus
               <-------               
         INTRO.BAS
         If game won
           <--> DoWin
           <--> DoCredits 

From this it can be seen that gameplay is divided as follows:

  INTRO.BAS : Manages lives, passing from level to level etc.
  DoLevel   : Loads specific level and set variables to begin new game
              DoLevel passes to DoGame
  DoGame    : Manages the playing of any one particular game. This is where the
              main game loop is.
              DoGame calls DoTick once per loop
  DoTick    : Manages the movement and drawing of sprites.

These are looked at in more detail later on.

2) INITIALISING
-- ------------

To start playing the game, the user runs ANTS.BAT. This does the following:
1) Load MIDI drivers
2) Runs INTRO.BAS (/SY is a parameter)
3) Unload MIDI drivers

If NOSOUND.BAT is used, the MIDI drivers aren't loaded and the  /SN parameter 
is used instead. If neither is used INTRO will not begin. This stops the
user running is straight off and causing a crash due to no MIDI drivers.

INTRO.BAS displays the logo screens and then presents the main menu. It 
manages the game in terms of level progression, lives etc. LEVEL.BAS 
actually runs the level. Because of the way it is set up, only the following
variables need to be passed between the two.

            From INTRO to LEVEL             From LEVEL to INTRO 
retvalue :  0 = Never passed, used as       0 = Never used, again used 
              a check that LEVEL hasn't       as a cmd prompt check.
              been run from the cmd prompt. -1 = Level was lost	
            1 = Normal game		    1 = Level was won	
            2 = Load game

retvalue2:  0 = Normal game                 Not changed unless loadgame
            1 = Stand alone

gamefile$:  Either the level file for a     Not changed	
            normal game or save file for
            a load game.
 
snd      :  1 = Use sound		    Not changed	
            0 = Don't use sound  

musicon  :  Passed back unchanged           The piece of music currently
            (usually anyway)                being played.
                 
level    :  Current level                   NOT USED : LEVEL works only
                                            based on gamefile$

lives    : No. lives left                   Altered only by INTRO


NOTES:

1) LEVEL always has responsibility for loading a saved game. When information is
passed back to INTRO, retvalue2 is altered to reflect whether the loaded game
is a stand-alone or part of the main game. So, if a player loses a life on
a saved game, when the game restarts it is run as a non-saved game (ie
starting from the .MAP file rather than the .SAV. Of course this means that
if the original .MAP file is not present an error will occur. In retrospect
this is unfortunate but it is too late to change at this late stage. To
remedy the problem, the .SAV format would have to be modified to also
save the original level data.


4) THE INTRO MENU SYSTEM
-- ---------------------

The INTRO module is simple and needs little explanation. It first loads
the title screens. These are BLOADED into an array (getscreen()) which is
then PUTed onto a Screen 7 screen. The Menu system is all done in screen 7.
The instructions section is Screen 9. The text is loaded from DATA\ins.txt.,
with the images loaded from within the program.

INTRO also displays the Mission/Win briefings. These are loaded from
DATA\mission.txt and DATA\win.txt respectively.

5) GAMEPLAY
-- --------

Once control is passed to LEVEL, it examines retvalue and retvalue 2 to
discover whether the game is a load-game and whether it is a stand-alone 
game. Stand-alone and non-saved games are run in the same way. InitWorld
is used to load the level data. For saved games, DoLoadGame is used
instead.

Control begins with DoLevel. This calls the InitWorld routine. It draws out
the level for the first time and displays the info box at the start of the
level. It then invokes DoGame.

DoGame is the main game loop. It checks for keyboard input, updates the
sidebar and checks if the game has been won or lost. It also calls DoTick
once per loop. This manages the sprites. Each time it is invoked it calls
the DoSprite routines twice. There are two images for each sprite, which,
when flipped between, creates a walking/flying effect. DoTick manages the
switching.

DoSprite is called for each sprite individually. It used the DoFree routine
to check if the square a sprite is walking onto is free. It also runs
DoCheck which handles and special properties that that square might have. 
Note that DoFree handles the opening of locks. Note also that DoFree is
run for every square that the sprite is on (may be two or three) whereas
DoCheck only applies to the square that the sprite is mainly on.

After each sprite movement the level images has to be repaired. This is done
using the DrawHideSprite routine. During each loop of DoSprite, an array
called dplace(x,y) records whether or not a tile needs redrawing. Then, when
all sprites have been moved, DrawHideSprite redraws all tiles that are
flagged for redrawing (ie. set as 1 in dplace.)

Tiles are drawn using the DrawPlace routine.

6) MIDI
-- ----

MIDI music is played using the QMIDI routines developed mainly by Jesse
Dorland. For the documentation of these routines and questions pertaining to
them you should contact as below. (Note:These links were provided with the
QMidi v4.1 documentation, I have not tested them.)


 E-mail:    jessedorland@hotmail.com
 Qeb-site:  http://members.tripod.com/~jdorland/qmidi/index.html

7) FILE FORMATS
-- ---- -------

There are three data files used: .spr, .map and .sav.

A).SPR

This is a byte by byte memory map of an image. An image is captured
into an array using the GET statement. The BSAVE command is then used to
copy the array to a disk file. To load the images, it is BLOADed into
an array which is the PUTted onto the screen.

B).MAP

This is the format in which level data is saved. It is a sequential file
which the lines corresponding to the following:

  1) Any comment *usually "Ants Sprite"
  2) Version (v1.2 for Ants the Exodus v1.0)
  3) Level title
  4) Level Author
  5) Date written
  6 - 25) Details of the map layout. Each tile is represented by a two
          digit number corresponding to the codes for each type of tile.
  26) The Number of sprites on the map
  For each sprite
    i) Sprite type
    ii) Sprite pos x
    iii) Sprite pos y
    iv) Sprite init. direction
    v) Sprite turn direction
  Then:
  No. of supply posts
  For each supply post
    i)Pos x
    ii)Pos y          
    iii)For slots 1- 10
        type of item
  Then:
  Stage 1 time limit
  Stage 2 time limit

C) .SAV

This is also a sequential file:

  1) Level filename
  2) Level title
  3) Date saved
  4) Level author
  5) Date written
  6) No. of comment lines <--To allow for future alterations
  7) Lives left
  8) Is it a fullgame (1-yes,0-no)
     If yes then
       i) Level
  9) Map of level layout (see above)
  10) No. sprites
     For each sprite
     i) Type
     ii) Pos x
     iii) Pos y
     iv) Direction
     v) Rotation
     vi) Moving?
     vii) Horizontal motion per tick
     viii) Vertical motion per tick
  11) No. supply posts
     For each supply post
     i) Pos x
     ii) Pos y
     For slots one to 10
       iii) Contents of slot
  12) St1 Time limit
  13) St2 Time limit
  14) Current tick
  15) Has exodus taken place?
  16) Start square x
  17) Start square y
  18) Finish square x
  19) Finish square y
  20) For each item type
      i) No. held
  21) Item selected

