     DON'T SHOOT THE QL

     by Dilwyn Jones, 2021

     "Don't Shoot The QL" is a game written for the Crap
Sinclair Games competition, 2021. The game is freeware - it
may be freely copied for all on a no-profit basis.

     It is written in QL SuperBASIC and needs Toolkit 2. The
compiled version supplied was compiled with the Turbo
compiler. It can be run in SBASIC on an SMSQ/E system too.

     It should be run in mode 8 on a QL, but can be used in
high colour modes on systems which feature those modes (e.g.
on QPC2). It can be compiled with either QLiberator or Turbo,
to enable it to run a bit better on slower QL systems.

     The aim of the game is to shoot down named retro
computers, but avoid shooting down any QLs. You score points
dependent on the size of the computer name (smaller ones are
harder to hit, so score more points). A QL carries a negative
score, so you lose points for accidentally shooting down a
QL. Bonus points are given for shooting down the occasional
Golden Mac which flies overhead.

     Control the canon with the left and right cursor arrow
keys, and fire using the space bar, ENTER or even the up
arrow key.

     The game features a high score table and a settings menu
to change various game options such as running speed and the
number of targets. Written in BASIC, it is quite easy to
change the way the game works - there are a number of
configuration options at the start of the program to allow
you to change such things as where the high score table data
file is stored and how long each game runs for by default.
The program is extensively commented with REM statements to
help you understand the code.

           ----------------------------------------
           "DON'T SHOOT THE QL"         SCORE:263
           ----------------------------------------
                      [MAC]
               PC
                            SPECTRUM
           VIC20
                                        QL
                  ZX81

                        |


                       /^\
           ----------------------------------------
           ZX80 4                        TIME:45
           ----------------------------------------




     CONFIGURING THE GAME

     You can make permanent changes by altering the first few
lines of the program and recompiling it, or temporary ones by
varying the same settings in the program while it is running.

     sound_on% - this controls whether the sound effects are
turned on or not. 1 means the sounds are played, while a
value of 0 mutes the sound.

     game_duration - this is the number of seconds which each
game lasts. 60 seconds is probably a good value to start
with.

     gun$ - a three character string representing the gun.
Set to "/^\" by default, but change it to whatever floats
your boat. Or whatever fires your missile.

     missile$ - a single character to represent the missiles
fired. A vertical bar "|" by default.

     lines% - this is the number of lines of computers to
shoot at. One computer per line. More lines make it more
interesting as there will be more objects to shoot at (and
more QLs to avoid shooting!) but the more lines of objects,
the more it starts to affect the running speed on slower
systems. So experiment a little with values from 1 to 15 to
see what suits you best on your system. Start with a
mid-range value. Ultimately, you have to use your judgement
which computer is best to fire at to try to increase your
score.

     game_speed% - this is a variable to adjust the delay
factor within the program to adjust the running speed on fast
systems such as QPC2. The value can range from 1 (no delay -
full speed) to 9999 (maximum slow-down). For a standard QL,
set this to 1 for no delay at all. For QPC2, you may need a
value from 2000 to 5000 depending on the speed of the
computer.

     comp_frequency% - this controls how frequently new
computers are launched. On a blank line, there is a "1 in
comp_frequency%" chance that a new computer will be launched
at random on that line.

     mac_frequency% - regulates how often one of the bonus
points Golden Macs is launched on the top line, above the
other computers. This means that when the line is blank,
there is a "one in mac_frequency%" chance of launching a
Golden Mac (which is nothing more than the name MAC written
in yellow!). 50 is probably a good value to start with, but
since it's a special bonus points target, you may prefer to
use a higher value which will result in fewer of these being
launched, to make the game more interesting.

     hiscore$ - the name of the file which stores the high
score table. The table is just a list of 10 names and their
scores. The filename should include drive name, number,
directory (if on a system with directories) and the filename.
There is no need for a particular filename extension, I
normally use _dat just to show it's some form of data file.

     Further on in the program, you'll see a short series of
DATA statements. These contain the names of the computers
used, along with the number of points for hitting that
computer. Apart from the QL and its negative score, you can
change the names and scores, e.g. if you find it offensive to
shoot down ZX81s, just change its entry in the data
statement. Here's an example, the line number may change a
little if I've made changes to the program since writing
these instructions:

     3260 DATA "ZX81",4

     As an example we'll change this to a TRS80 computer
having a score of 3:

     3260 DATA "TRS80",3

     As the program stands, the name should be no more than 8
letters long and score should be comparable to the range of
score values currently in the DATA statements (values not
checked, but since hitting a QL deducts 10 from your score
and a Golden Mac adds 20 bonus points, it makes sense to keep
the individual computer score from 1 to 8).

     Although you should not change the name of the QL entry,
you can change the negative score for hitting a QL, e.g.
change the penalty from -10 to -20 so that you are penalised
more for accidentally hitting a QL.


     STARTING THE PROGRAM

     To start the program, just LRUN the BASIC version, or
EXEC the compiled version. The BASIC version will probably be
too slow for an original QL, although you can alter a few
variables in the program to adjust the speed for whatever
system you run it on.

     The BASIC version:

     LRUN dddn_dstheql_bas

     or, for the compiled version:

     EXEC dddn_dstheql_task

     where dddn_ is the drive name and number it's being
started from.

     Once you've started the program, it begins with the
current high score table. If it can't find the high score
table, it will start with a table consisting of my name and
some fairly low value scores.

     If ever you encounter a problem with the high score
table, e.g. a Bad Or Changed Medium error report, you can
safely delete that high score table and the program will
create a new one as it runs - the new high score table is
saved when you quit from the program.

     At startup, you get a screen like this:


     ----------------------------------------
     " D O N ' T   S H O O T   T H E   Q L "
     ----------------------------------------

                 HIGH SCORE TABLE

                 Dilwyn       100
                 Dilwyn        90
                 Dilwyn        80
                 Dilwyn        70
                 Dilwyn        60
                 Dilwyn        50
                 Dilwyn        40
                 Dilwyn        30
                 Dilwyn        20
                 Dilwyn        10

       F1-Setup    SPACE-Play    ESC-Quit

     ----------------------------------------


     Pressing SPACE or ENTER starts the game, while pressing
ESC quits from the program. Pressing F1 enters the game setup
menu, which lets you make temporary changes to some the
settings for this session.

     The list of settings is a small table of six items. Move
the highlight bar up and down the list with the cursor up and
down arrow keys, and vary the setting values with the cursor
left and right arrow keys (use SHIFT left and right arrow
keys to make the values change faster). Press SPACE to return
to the high score table.

     In the Settings menu you can turn the sound off or on,
vary the game duration, change the number of lines on which
computers appear, change the frequency of standard computers
and Golden Macs, and finally vary the game speed. Note that
any settings altered are not saved, they are only to let you
make temporary changes, e.g. to temporarily mute the sound
effects, or to experiment with the settings before making
more permanent changes as described above.

     ----------------------------------------
     " D O N ' T   S H O O T   T H E   Q L "
     ----------------------------------------

       ▲▼-Select  ◄►-Adjust  SPACE-Continue

          Sound effects:            On
          Game duration (seconds):  60
          Lines of computers:       5
          New computers, 1 in:      50
          New Golden Macs, 1 in:    50
          Game speed (1 to 9999):   2000
          (1=full speed, 9999=slow)

     ----------------------------------------


     IDEAS FOR DEVELOPMENTS

     The game is written in BASIC, so should be fairly easy
to alter. Here are some suggestions.

     For those with systems such as QPC2, you may wish to
experiment with using the QL Sampled Sound System or the new
AY-sound emulation on QPC2 to improve the sound effects. The
existing sound effects use the BEEP command and can be found
in three procedures called Zap, MacZap and Oops. These
contain REM statements to describe what each is used for.

     Timing. Currently the slowdown factors and relative
speeds of the various computers are handled using simple
countdown variables in the main program loop, e.g. only do
something every one in ten iterations of the loop. While this
is a fairly simple way to control timings, it's pretty bad
for multitasking as it places a heavy load on the system
while the game wastes time doing nothing for brief bits of
time. A better way to handle speed control might be to use a
command which suspends the QL for a frame or two every now
and then. It might be possible to use INKEY$ with a time
value, e.g. INKEY$(#0,1) instead of INKEY$(#0), but the
problem with that is that INKEY$ delay values are cut short
when keys are pressed, so using INKEY$ in an action game
using frequent keypresses won't work properly. So, instead,
consider using something like SUSPEND_TASK in Turbo Toolkit
to introduce proper delays that dont put too much load on the
system during delays.

     There is plenty of scope to improve the program
graphics, with more use of colours, brighter borders, better
screen layouts. Bear in mind the title of the competition for
which this game was written before being too critical of the
program's current appearance!

     If you are familiar with redefining QL character fonts,
you may like to redefine some characters in a font to improve
the graphics displays, e.g. program a few characters to make
a better missile or a better gun to fire with. Or even making
better explosion effects when the missile hits something. All
the game action takes place in screen window #0, so once you
have created the characters simply install them as a new font
for #0, e.g. using the CHAR_USE command of Toolkit 2 and
change the characters used in the program to match the
characters you redefined in the font.

     By studying the code handling the missile firing, you
may like to create a mechanism whereby certain computers can
fire back at you! The Golden Mac would be a good choice for
this. The screen is mapped onto an array called scr$ which
could be used to test if the bomb dropped had hit another
computer, your gun, or even your missile on its journey up.

     The program currently uses a FLASH command when printing
some scores. Many systems just ignore such FLASH commands.
Some text flashes on a QL, but doesn't on an emulator.

     The program always starts with its windows at a fixed
position in the top left of a high resolution display. The
WINDOW command in line 270 (at the time of writing) controls
this: 270 WINDOW #0,484,242,14,7  - just change the 14 and 7
to different x and y coordinates respectively if you want it
to start at a different location on a high resolution screen.

     With any such changes, do bear in mind that even as it
stands the program is a bit too slow for original QL systems
without being compiled. So don't be too ambitious!


     RECOMPILING

     The program does not open any windows of its own, and
only uses screen channel #0. Compile by setting WINDOWS on in
Turbo or QLiberator so that the program starts with windows
already open. Since compiling with these options copies the
current outline size of all open windows, minimise these
windows with a command such as Toolkit 2's WTV or WMON
commands before recompiling to avoid an "out of range at line
0" error when it starts on a 512x256 QL screen mode.

     There are some undimensioned strings in the program. If
compiling with Turbo, you will get the usual report along the
lines of "Warning at 0: DIM gun$(100) assumed." in the
compilation report. This will not prevent successful
compilation, but you may wish to dimension the strings gun$,
mac$, hiscore_file$, name$ and missile$ to appropriate
lengths if you are particular about these things.

     If using QLiberator, and you wish to change the filename
of the program, be careful with the length odf the filename.
QLiberator in particular doesn't allow room for the longest
possible QL filename in its compiler control panel.


     DEVELOPMENT HISTORY

     1.00 14th February 2021
     First release.

     1.01 16th February 2021
     Fixed high score table problem (wrong loop increment).

     "Out Of Range At Line 0" compile error (pre-compilation
window outline size copied to compiled program problem)
fixed.

     Reduced filename length to make it easier for systems
with 8.3 type filename length restriction.

     Fixed 'bad parameter' error reported due to stray comma.

     Corrected a few typos in this manual.

     Added plain text version of manual to make it easier for
those without Quill.

