This text file accompanies TRK19.BAS, The Track Editor v19 for 4d

(0)   CONTENTS:
      (1)   INTRODUCTION
      (2)   THE MAIN SCREEN:
         (2.1) The main window:
         (2.2) The view window:
         (2.3) The track window:
         (2.4) The text line:
            (2.4.1)  The information part
            (2.4.2)  The file name
            (2.4.3)  The altered signal
            (2.4.4)  The selected track item
            (2.4.5)  The size of the water patch
            (2.4.6)  The scale of the main window
            (2.4.7)  The current background
            (2.4.8)  The selelected track
      (3)   FILES:
         (3.1) Opening files
         (3.2) Saving files
         (3.3) Quiting the track editor
      (4)   THE HELP SCREEN
      (5)   KEYS:
         (5.1) View window manipulation
         (5.2) File handling and other
         (5.3) Altering scenery
         (5.4) Altering track
      (6) GUIDE TO THE USE OF TRK19.BAS
         (6.1) The basics of building a track
            (6.1.1)  Laying track  
            (6.1.2)  Deleting track
            (6.1.3)  Creating hills/valleys
            (6.1.4)  Deleting hilly areas
            (6.1.5)  Creating water areas
            (6.1.6)  Deleting water areas
         (6.2) Keyboard layout and use
         (6.3) Screen display
         (6.4) Track/scenery
         (6.5) Other
      (7) EXTRA STUFF

(1)   INTRODUCTION:

      TRK19.BAS is a track editor designed to create and edit
      tracks for 4d.  It was written because the track editor
      given with 4d does not allow you to alter the scenery of
      the track - hills and water, just the track itself.  As
      this facility makes for much more interesting tracks a
      decent track editor needed to be written.  

      Now follows a comprehensive (if I finish it that is)
      guide to the features of the Track Editor, to complement
      the key reference guide in the program itself.

(2)   THE MAIN SCREEN:

      The main screen (as opposed to the file
      loading/saving/help screens) has 3 blocks of graphics and
      a line and column of text.

      (2.1) The main window:
            this is the main area of the screen, taking up most
            of it.  It displays the scenery and the track in
            each square.  The cursor is in this window, and is
            shown by the absence of the lines around the block
            where it is.  The cursor can be moved by the keys
            s x k l (as for Elite et al)

      (2.2) The view window:
            this is at the top right of the screen and comprises
            of two concentric squares.  The outer square
            represent the whole track, a 30*30 grid.  The inner
            (filled) square represents what you can see in the 
            main window when the screen was last redrawn.  The 
            inner square can be moved by the cursor keys and the 
            screen is redrawn by pressing ENTER.
            NB:  editing in the main window edits where you can
            see in the main window, even if the view window has
            moved but you havn't redrawn the main window.

      (2.3) The track window:
            this is at the bottom right of the screen, comprising 
            of 4 squares in a 2*2 gird, and displays the selected 
            piece of track.  The selected track can be altered by 
            i [ (which alters the type of track) and o p (which 
            alters the piece of track).
                 
      (2.4) The text:
            there is text along the bottom line and down the right
            hand column between the view and track windows.  There
            are several pieces of information; these appear on a line
            across the bottom of the screen: (from left to right)
            
            (2.4.1)  The information part.  This is where you will
                     be prompted to confirm quitting, abandon edit,
                     etc..  This usually displays a message about
                     how to activate the help screen.
            (2.4.2)  The file name.  This is the file that you are 
                     currently working on - the last name you saved
                     under or loaded from.
            (2.4.3)  Altered signal.  If you alter the current track            
                     'Alt' will appear here as a reference.
            (2.4.4)  The selected track item - what is displayed in
                     the track window (see above).  It displays the 
                     track type (I have subdivided the track into 12 
                     sections: Normal, Banked, Ramps, etc.).  This 
                     can be altered by the keys i [ (up and down 
                     respectively, moving cyclically).  It also 
                     displays the number of the selected track piece
                     within the type - for example 5/23 (you have
                     selected the 5th item out of 23 in the track type)
                     .  This can be changed by the keys o p (up, down
                     as before).
            
            Along the right hand edge of the screen are information 
            relating to four keys; with the key press on the first line, 
            a summary of what it changes on the second and the current 
            setting on the third. (from top to bottom)
            
            (2.4.5)  The current size of the water patch (Small/Medium/
                     Large).  The large patch fills a 3*3 square, the 
                     medium patch fills a 2*2 square and the small patch 
                     fills 1 square.  This is used by 2 of the ways to 
                     lay down water (see below).  It can be increases 
                     (cyclically) by pressing F5.
            (2.4.6)  The scale of the main window.  There are several
                     different scales to use to zoom in or out of the
                     track.  The information displayed is the zoom
                     factor (as a fraction of the original and default
                     size) and the size (in pixels) of each square.
                     This is changed by pressing F6, but has no effect
                     untill the screen is redrawn (by pressing ENTER).
            (2.4.7)  The current background (Desert/Tropical/Alpine/
                     City/Country).  This can be altered by pressing
                     F8 which moves between them cyclically.  There
                     is no direct access (as you don't really have
                     to change it often).
            (2.4.8)  The selected type of track (Banked/Normal/Mud/
                     Ice).  This is the track used for the automatic 
                     tracklayer.  It can be altered in two ways; 
                     pressing SPACE moves between them cyclically,
                     and they can be directly accessed by the keys
                     F9 F10 F11 F12 respectively.

(3) FILES:
      (3.1) Opening files:
            When opening a track file, you are asked for the 4d
            directory - where the .trk files are.  If the default
            option is correct then just press RETURN.
            
            NB: this is the only place that TRK19 can crash that I know
            of (unless you do something very odd); if there are no
            .trk files on the directory that you enter or the path 
            doesn't exist then it will crash.  The likelyhood of
            losing work because of this is fairly slim however, 
            because of the safegaurds against accidentally quitting.
            This will be fixed in later versions.

            It will then display a list of all the track files in
            that directory, and ask for the filename of the track you
            want to edit.  The default option (select buy just
            pressing return) is blank - I have created blank.trk as a
            blank track to start new tracks.  If you type in the name
            of a file that doesn't exist, then a track file of that
            name will be created.  TRK19 does not created the high
            score files (.hig); these are automatically done when
            using the track file in 4d.  TRK19 will display the
            percentage of the file read in the top right hand corner.
            When starting the program, it will also display a
            percentage of the data read.  If you have altered the
            current track since it last was saved, then you will be
            prompted to save it before you load another track.

      (3.2) Saving files:
            When saving a file the screen will clear and the current
            directory of files will be shown again and you will be
            asked for the filename you want to save to.  Pressing
            return will cancel saving the file.  Typing * and RETURN
            will save the file with the same name that you loaded it
            with.  Otherwise just type the filename (do not add the
            .trk extension) and press RETURN.  The percentage of the
            track saved will appear in the top right hand corner of
            the screen.

            NB: once I have sorted out the bug mentioned earlier (in
            3.1) there will be an option to enter a new directory
            here, but that is too risky at the moment.

      (3.3) Quiting the track editor:
            If you have altered the current track since it last was
            saved, then you will be prompted to save it.  You will
            then be asked whether you really want to quit.  To quit
            you must type a capital Y.

(4)   THE HELP SCREEN:
      The on-line help screen is a key reference, and is
      activated by pressing ESC.  Then press the key you want
      to know the action of - this will appear below the
      keyboard graphic.  Press Y to quit (not necessairly capital)

(5)   KEYS:
      (5.1) View window manipulation:
            cursor keys moves the cursor around the whole track
            ENTER       reprints the main window
      
      (5.2) File handling and other:
            q           quits the track editor, with prompts to 
                        save changes
            w           writes the current track to a file
            t           opens a new track, with prompts to save
                        changes
            F8          increases the type of background
            F6          changes the scale factor for the main window
      
     (5.3)  Altering scenery:  (hills, water)

            a           raises the scenery where the cursor is
            CTRL+a      lowers the scenery
            F5          changes patch size of water
            \           lays a patch of water (depends on F5)
            d           stores the cursor co-ordinates
            c           inverses (swaps hills and valleys) scenery
                        from d to the cursor in a square
            v           raises scenery from d to the cursor in a square
            CTRL+v      raises scenery from d to the cursor in a line
            r           lays water from d to the cursor in a square
            CTRL+r      lays water from d to the cursor in a line (this
                        depends on the patch size; the F5 toggle)
            e           makes all the low ground from d to the
                        cursor water - this toggles ground and water
            CTRL+e      make all the scenery from d to the cursor water
           
            z           decreases the scenery code by one
            F1          sets the scenery code to 06 - raised ground
            F2          sets the scenery code to 10 - one edge up, one down
            F3          sets the scenery code to 14 - one vertex up
            F4          sets the scenery code to 18 - one vertex down
            1           sets the scenery code to 1 - all water
            2           sets the scenery code to 2 - SW corner is water       
            3           sets the scenery code to 3 - NW corner is water
            4           sets the scenery code to 4 - NE corner is water
            5           sets the scenery code to 5 - NW corner is water

      (5.4) Altering track

            F9          selects banked track for the autotrack
            F10         selects normal track for the autotrack
            F11         selects mud track for the autotrack
            F12         selects ice track for the autotrack
            d           stores the cursor co-ordinates
            f           stores the cursor co-ordinates
            ,           lays track from d to the cursor of the
                        selected type bending to the side where f 
                        was pressed
            .           deletes track from d to the cursor bending
                        to the side where f was pressed
            
            i           decrease the type of track by one
            [           increase the type of track by one
            p           decrease the track number by one
            [           increase the track number by one
            ;           lays the selected track number
            /           deletes the track item where the cursor is


(6)   GUIDE TO THE USE OF TRK19.BAS

      Not so much of a guide as a list of note and hints
      telling you roughly how to actually use The Track Editor.  I
      can't call it a FAQ really because I havn't been asked any
      questions, but I hope that information you would ask me is
      contained below (feel free to e-mail me if it is not).
      This also contains bugs, ideas for future versions, mutterings, etc..

      (6.1) The basics of building a track
            Here follows an idiots guide to building a track
            using TRK19.BAS:
            There are many ways of doing the same thing, and
            here are all of them, listed by task, with the
            manual ways first in each case.
            (6.1.1)  Laying track
                     *  select each piece in the track viewer
                        (pressing i o p [) and lay each piece
                        individually on the cursor (move the cursor
                        by pressing s x k l) by pressing ;
                     *  use AutoTrack by first selecting the track
                        type (press SPACE to toggle or F9-12 to
                        select direct - selected track type appears
                        in the right hand column), then press
                        d when the cursor is where you want the 
                        track to start, press f when the cursor is
                        on the corner (or on the lower side of a straight
                        piece of banking, for other straights where you
                        press f doesn't matter), then press , when the 
                        cursor is where you want the track to finish

            (6.1.2)  Deleting track
                     *  delete each piece individually by moving the
                        cursor over the piece and press /
                     *  use AutoTrack exactly the same as above but
                        press . instead of , and it will delete track
                        where it would have lain it using ,

            (6.1.3)  Creating hill/valleys
                     *  change each square covered to create whatever
                        shape you want by either decreasing the code
                        of the square by pressing z, or change to some
                        types direct by pressing F1-4 (usually a
                        combination - F1-4 gets to the the first of
                        each type of scenery - see 5.3)
                     *  raise a single square (and 8 border squares to
                        form the slopes) by moving the cursor to the
                        appropriate position and press a
                     *  lower a single square (and 8 border squares) by
                        holding down CTRL and pressing a
                     *  invert a square area (ie swop hills and valleys)
                        by pressing d when the cursor is where you want
                        one corner of the square to be and moving the
                        cursor to where the opposite corner is and
                        press c
                     *  raise a square area (and border squares to form
                        the slopes) by pressing d when the cursor is on 
                        one corner, then press v when the cursor is at 
                        the opposite edge
                     *  raise a line of squares (and border squares) to
                        create a ridge by pressing d at one of the ridge
                        and holding down CTRL and pressing v at the
                        other end

            (6.1.4)  Deleting hilly areas
                     *  delete each individual square by pressing z
                        and repeating until the square is at low ground
                     *  there is no built in feature for this, but you can
                        water everything (use d and CTRL+e - see 6.1.5)
                        then inverse water (use d and c - see 6.1.3) to get 
                        high ground, then inverse this to get low
                        ground.
                     
            (6.1.5)  Creating water areas
                     *  change each square into one of the 5 types of
                        water (whole square & 4 half squares) direct
                        by pressing 1-5
                     *  create a patch a water either a single square,
                        a 2*2 diamond, or a 3*3 octagon, (select using
                        F5, see which is selected at the right hand
                        column of text; Small, Medium or Large) by pressing 
                        \, either at the center of the patch (for small 
                        and large) or at the top right hand corner of 
                        the medium patch.
                     *  water a line with thickness of the current
                        water patch (select using F5) by pressing d at
                        one end of the line and holding down CTRL and
                        pressing r when the cursor is at the other end
                        of the line
                     *  water a square area by pressing d at one of the 
                        corners of the area, then pressing either r, e or
                        holding down CTRL and pressing e, depending on 
                        what you want:
                        r        turns everything into water, round off 
                                 the edges (an irregular octagon)
                        CTRL+e   turns everything into water
                        e        turns bare ground into water, and water
                                 into bare ground

            (6.1.6)  Deleting water areas
                     *  delete each individual square by pressing z
                        and repeating until the square is at low ground
                        or press F1 to turn it into rasied ground, then
                        press z once to turn it into lowered ground
                     *  there is no built in feature for this, but you can
                        inverse water (use d and c - see 6.1.3) to get 
                        high ground, then inverse this to get low
                        ground.
      
      (6.2) Keyboard layout & use
            The keys are designed in two sections, one for the  
            left hand which controls the scenery placement, and
            one for the right hand which lays the track.  This
            is designed to limit the movement of the hands to just
            the cursor keys.   The only stuff out of reach are the
            function keys and the number keys (which mainly do stuff
            manually which can be done faster automatically).
            It may seem that you can do it faster using these keys,
            but that's only because you can't be bothered to learn
            the automatic keys.  Here are a few hints:
            *  e/r and c/v are broadly equivilent - e/r works with
               water, and c/v works with hills.  (r/v are exactly
               equivilent when the water patch size is large)
            *  before doing anything which requires more than cursor 
               placement, d is *always* used to store the first set of 
               coordinates
            *  the automatic track layer (AutoTrack) is VERY flexible.
               For a bend between 2 points (d and the cursor) there
               are 2 different tracks, so you need to press f to
               distinguish between them.  You need to press f
               eith side of the line between d and the cursor and it
               will bend to that side (I usually press it at the corner
               to make sure).  It can also lay straight track - here
               f doesn't need to be set, except if you are laying banked
               track; here press f the side of the straight that you
               want to be low.  As AutoTrack needs f to work out what
               to lay when you first run TRK19 you need to press f to
               lay a straight line - otherwise for non-banking you
               don't need to press f at all (as it doesn't make any 
               difference) Pressing . instead of , deletes along
               exactly the same path that , lays on.
            *  when selecting track in the track window, if you change 
               between track types it skips to the first track item 
               in the new track type.  Also, changing the track number 
               changes it as if all the items where in one order (decrease 
               it from 1/23 will move it to 16/16 of the previous track 
               type, etc.)
            *  when quitting, you need to press capital Y to confirm: I got
               so pissed of with quitting acidentally that I put that in.

      (6.3) Screen display
            *  I havn't implemented the 'scrolling screen' that the native
               4d editor has got, mainly because it would take too long
               and look unattractive as a result.
            *  As before, changing the view window has no effect on what
               you are editing until you press ENTER to redraw the screen
            *  Sometimes some of the larger pieces of track will dissappear
               when you redraw some of the screen - say raise ground.
               This is because all the larger pieces are only one code
               in the top left corner and 1 or 3 other null codes (255,
               253,254) to make sure track doesn't overlap.  Unless I redrew 
               the whole screen after all such edits (tedious) or redrew
               the track piece that is effective (less tedious, but in
               most cases this would cause the track piece to be drawn
               several times) there's not much I can do.  Sorry!  (well
               not really...)  Anyway, I have thought of a decent way of
               doing this, so it will be solved in later versions.
      
      (6.4) Track/Scenery
            The colours are stored in wacol, hicol, trcol, lycol.  
            wacol is the water colour, hicol is the colour of the 
            high ground (getting the hang of this naming variables 
            lark) and trcol is the scenery colour.  Maybe not then.
            The reason why it's called this (and why the array that the
            scenery is stored in is tr(), and why the track is stored in
            ly() and lycol) is becase I wrote this originally as just a
            scenery editor - for editing .TRk files.  I havn't rationalized
            this (as I have most other references) because I can't be
            bothered really - and because of tradition.  Anyway...
            trcol is the low half of the slopes, and trcol+8 is the high
            half of the slopes, so values of trcol>8 just get white for
            the top half.  lycol is the track colour.  In future versions
            there will be facilities for changing the colour display when
            running the program, will the settings saved in a file - which
            will also include starting scale size, patch size, default
            directory, etc...

            The scenery looks alright, well as good as the 4d editor
            anyway.  However the track is fairly crap.  Most of the 
            actual track is alright, but the objects are pretty basic. 
            By the way, the code for the tracks is that normal is 3 
            lines thick, mud is 2 lines thick and ice is 1 line thick.
            Banking is three lines thick at the high edge, and one line 
            at the low edge, for the straights and corners.  The sections
            changing from banking to not banking are a little wierd; they
            look like a straight but a banking but they have an extra line
            at the non-banking end.  Anyway, this is done automatically
            by AutoTrack, so no worries there.  The start/finish pieces
            of track have a thick block across the road at one end, where 
            you travel towards the bar from the middle of the square.

            Sometime if I did this properly I'd just use small graphic files
            to get decent images, but for a usable basic program, the
            representations aren't that bad.  The only slow ones to print
            out are the high curves (as it draws the legs by lots of
            close lines - this should change pretty soon, using paint
            statement like other pieces of high track) and the 
            helterscelter curves, but as I almost never use either of these, 
            it's not too much of a bother to me.

            Having the enormous CASE statements in the track drawing file
            isn't ideal either, but it's one hell of a lot better than
            what was before it (a mass of interlinked GOSUB routines).
      
      (6.5) Other
            
            It will depend on what you have already, but myself having
            separate basic and 4d directories, find it a lot easier
            having created 2 batch files, one in each to change directory
            and load/run the approriate file.

            I actually have 3 batch files - one which runs FRED.EXE to
            alter the car.  The other major (even better than this) 
            extension to 4d is hacking into the car files.  If you've
            done this already then stop reading now, but if not, you can
            basically alter you car to go from rest to 245 mph in around
            5 seconds, and back down in 2 seconds, change when the car 
            it changes gear on automatic - even change the number of gears, 
            get digital readouts, analogue readouts of speed/revs, alter the
            sensitivity of the steering, alter the ride quality of the car,
            etc. - even make it so 4d crashes as soon as you start driving!
            However, as it's taken me some while to get to this stage, I
            don't feel inclined to tell you this.

(7)   EXTRA STUFF

      I wrote this program by myself over over a period of several
      years.  Versions 1-14 where on a monochrome laptop computer;
      v15 was the full 16 colour conversion!  It is now beginning 
      to reach the limits of size, mainly due to a complete 
      re-write from version 15 to 16 which tripled the number 
      of lines.  However, this has made the program much more 
      readable, and altering it is now considerably easier.
      The main difference between this and the previous version
      is the scalable size of the squares, enabling you to look at
      the whole track at once.

      I have to thank my Dad for letting my use his laptop when ever
      I could, and taking up copious amounts of space, and my sister
      Caroline, for letting my use her machine in the dark and mysterious 
      days when I didn't have one of my own.  Also I should thank Tim W
      (trolls can do that) for, while not exactly testing it, offering
      any amount of advice containing aparently random amounts of 
      usefullness/practically/raisins/etc..

      Feel free to change this program, but I would like to be told
      of any major changes (as opposed to just changing to colour scheme
      - people have complained of severe brain damage after looking at
      my Windows colour scheme), as well as any gripes, bugs, suggestions,
      comments, requests for the next version, etc. - anything at all 
      really.  Feel free to pass this program (TRK19.BAS), as long as 
      you include this text file with my name attached to the current 
      program.  Modify this file if needs be, but please don't take 
      this for your own program, given all the work I've put into it.
      
      My e-mail address is tjg21@cam.ac.uk and should be valid until 
      the middle of 1997.

      Thanks for using TRK19,

         Tim Granger,  Cambridge,  4th January 1995
