
   Super Star Trek 3 (SST3) For (modern versions of) BBC Basic
   ===========================================================

This is a version of the Super Star Trek program that was published in
David Ahl's 1978 book BASIC Computer Games. It has been converted to run
in BBC BASIC for SDL or Console, and somewhat modified to make it easier
(or optionally harder) to play, but for the most part the game play has
not been significantly altered other than a few enhancements.


Files and Execution Environment
-------------------------------

SST3.bas - BBC BASIC source code for SST3
SST3.bbc - Source code for SST3 in tokenized form
SST3.exe - Compiled version of SST3 for Windows
SST3.txt - This doc file

The SST3.bbc file loads directly into BBC Basic for SDL or Android.

The SST3-exe.exe file was produced by compiling the program with BBC Basic
for Windows version 6.13a (running under wine on my Ubuntu 20.04 system).
The compiler was set to use a graphics window size of 600 by 678 pixels,
or about 50 lines of 75 characters. This is hardcoded into the program,
resizing the window will not change the size of the text area.

For Windows or wine users the easiest way to run the SST3 program is
to double-click the SST3-exe.exe file. The two exe's in the name is
to distinguish it from the other files if file extensions are hidden.

To edit the code and run other BBC BASIC programs get a full BBC BASIC
for SDL package, and optionally also the BBC BASIC for Console package.
BBC BASIC for SDL is at: https://www.bbcbasic.co.uk/bbcsdl/index.html
BBC BASIC Console is at: https://www.bbcbasic.co.uk/console/index.html
These packages are available for Windows, Linux and Mac, and the SDL
version is also available for Android (Super Star Trek on a phone!).

The program will also work with the console version of Matrix Brandy
(tbrandy/tbrandy.exe) which is at: http://brandy.matrixnetwork.co.uk/
Some things are slightly different, see the notes below. This program
does not work correctly with the graphical version of Matrix Brandy
(brandy/brandy.exe) due to COLOUR issues.


Instructions for the original Super Star Trek
---------------------------------------------

      INSTRUCTIONS FOR 'SUPER STAR TREK'
 
 1. WHEN YOU SEE \COMMAND ?\ PRINTED, ENTER ONE OF THE LEGAL
     COMMANDS (NAV,SRS,LRS,PHA,TOR,SHE,DAM,COM, OR XXX).
 2. IF YOU SHOULD TYPE IN AN ILLEGAL COMMAND, YOU'LL GET A SHORT
     LIST OF THE LEGAL COMMANDS PRINTED OUT.
 3. SOME COMMANDS REQUIRE YOU TO ENTER DATA (FOR EXAMPLE, THE
     'NAV' COMMAND COMES BACK WITH 'COURSE (1-9) ?'.)  IF YOU
     TYPE IN ILLEGAL DATA (LIKE NEGATIVE NUMBERS), THAN COMMAND
     WILL BE ABORTED
 
     THE GALAXY IS DIVIDED INTO AN 8 X 8 QUADRANT GRID,
 AND EACH QUADRANT IS FURTHER DIVIDED INTO AN 8 X 8 SECTOR GRID.
 
     YOU WILL BE ASSIGNED A STARTING POINT SOMEWHERE IN THE
 GALAXY TO BEGIN A TOUR OF DUTY AS COMANDER OF THE STARSHIP
 \ENTERPRISE\; YOUR MISSION: TO SEEK AND DESTROY THE FLEET OF
 KLINGON WARWHIPS WHICH ARE MENACING THE UNITED FEDERATION OF
 PLANETS.
 
     YOU HAVE THE FOLLOWING COMMANDS AVAILABLE TO YOU AS CAPTAIN
 OF THE STARSHIP ENTERPRISE:
 
 \NAV\ COMMAND = WARP ENGINE CONTROL --
     COURSE IS IN A CIRCULAR NUMERICAL      4  3  2
     VECTOR ARRANGEMENT AS SHOWN             . . .
     INTEGER AND REAL VALUES MAY BE           ...
     USED.  (THUS COURSE 1.5 IS HALF-     5 ---*--- 1
     WAY BETWEEN 1 AND 2                      ...
                                             . . .
     VALUES MAY APPROACH 9.0, WHICH         6  7  8
     ITSELF IS EQUIVALENT TO 1.0
                                            COURSE
     ONE WARP FACTOR IS THE SIZE OF
     ONE QUADTANT.  THEREFORE, TO GET
     FROM QUADRANT 6,5 TO 5,5, YOU WOULD
     USE COURSE 3, WARP FACTOR 1.
 
 \SRS\ COMMAND = SHORT RANGE SENSOR SCAN
     SHOWS YOU A SCAN OF YOUR PRESENT QUADRANT.
 
     SYMBOLOGY ON YOUR SENSOR SCREEN IS AS FOLLOWS:
        <*>  = YOUR STARSHIP'S POSITION
        +K+ = KLINGON BATTLE CRUISER
        >!< = FEDERATION STARBASE (REFUEL/REPAIR/RE-ARM HERE!)
         *  = STAR
 
     A CONDENSED 'STATUS REPORT' WILL ALSO BE PRESENTED.
 
 \LRS\ COMMAND = LONG RANGE SENSOR SCAN
     SHOWS CONDITIONS IN SPACE FOR ONE QUADRANT ON EACH SIDE
     OF THE ENTERPRISE (WHICH IS IN THE MIDDLE OF THE SCAN)
     THE SCAN IS CODED IN THE FORM \###\, WHERE TH UNITS DIGIT
     IS THE NUMBER OF STARS, THE TENS DIGIT IS THE NUMBER OF
     STARBASES, AND THE HUNDRESDS DIGIT IS THE NUMBER OF
     KLINGONS.
 
     EXAMPLE - 207 = 2 KLINGONS, NO STARBASES, & 7 STARS.
 
 \PHA\ COMMAND = PHASER CONTROL.
     ALLOWS YOU TO DESTROY THE KLINGON BATTLE CRUISERS BY
     ZAPPING THEM WITH SUITABLY LARGE UNITS OF ENERGY TO
     DEPLETE THEIR SHIELD POWER.  (REMBER, KLINGONS HAVE
     PHASERS TOO!)
 
 \TOR\ COMMAND = PHOTON TORPEDO CONTROL
     TORPEDO COURSE IS THE SAME AS USED IN WARP ENGINE CONTROL
     IF YOU HIT THE KLINGON VESSEL, HE IS DESTROYED AND
     CANNOT FIRE BACK AT YOU.  IF YOU MISS, YOU ARE SUBJECT TO
     HIS PHASER FIRE.  IN EITHER CASE, YOU ARE ALSO SUBJECT TO
     THE PHASER FIRE OF ALL OTHER KLINGONS IN THE QUADRANT.
 
     THE LIBRARY-COMPUTER (\COM\ COMMAND) HAS AN OPTION TO
     COMPUTE TORPEDO TRAJECTORY FOR YOU (OPTION 2)
 
 \SHE\ COMMAND = SHIELD CONTROL
     DEFINES THE NUMBER OF ENERGY UNITS TO BE ASSIGNED TO THE
     SHIELDS.  ENERGY IS TAKEN FROM TOTAL SHIP'S ENERGY.  NOTE
     THAN THE STATUS DISPLAY TOTAL ENERGY INCLUDES SHIELD ENERGY
 
 \DAM\ COMMAND = DAMMAGE CONTROL REPORT
     GIVES THE STATE OF REPAIR OF ALL DEVICES.  WHERE A NEGATIVE
     'STATE OF REPAIR' SHOWS THAT THE DEVICE IS TEMPORARILY
     DAMAGED.
 
 \COM\ COMMAND = LIBRARY-COMPUTER
     THE LIBRARY-COMPUTER CONTAINS SIX OPTIONS:
     OPTION 0 = CUMULATIVE GALACTIC RECORD
        THIS OPTION SHOWES COMPUTER MEMORY OF THE RESULTS OF ALL
        PREVIOUS SHORT AND LONG RANGE SENSOR SCANS
     OPTION 1 = STATUS REPORT
        THIS OPTION SHOWS THE NUMBER OF KLINGONS, STARDATES,
        AND STARBASES REMAINING IN THE GAME.
     OPTION 2 = PHOTON TORPEDO DATA
        WHICH GIVES DIRECTIONS AND DISTANCE FROM THE ENTERPRISE
        TO ALL KLINGONS IN YOUR QUADRANT
     OPTION 3 = STARBASE NAV DATA
        THIS OPTION GIVES DIRECTION AND DISTANCE TO ANY
        STARBASE WITHIN YOUR QUADRANT
     OPTION 4 = DIRECTION/DISTANCE CALCULATOR
        THIS OPTION ALLOWS YOU TO ENTER COORDINATES FOR
        DIRECTION/DISTANCE CALCULATIONS
     OPTION 5 = GALACTIC /REGION NAME/ MAP
        THIS OPTION PRINTS THE NAMES OF THE SIXTEEN MAJOR
        GALACTIC REGIONS REFERRED TO IN THE GAME.


Changes from the original Super Star Trek program
-------------------------------------------------

The original instructions still apply for the most part, the main
deviations from these instructions are the library computer option 0
(cumulative record) has been moved from option 0 to option 6, and the
default SRS display uses simple E K and B symbols to indicate the
Enterprise, Klingons and Starbases.

The source code for the original program was published in the book
"BASIC COMPUTER GAMES MICROCOMPUTER EDITION", edited by David Ahl and
published by his company Creative Computing in 1978. The source code
I started with for this version was (probably) downloaded from the
Vintage Basic Games site: http://www.vintage-basic.net/games.html

This source has two typos (that I know of).. in line 440 B9=2 is
supposed to be B9=0, and in line 1150 G(Q1,Q2)+120 is supposed to be
G(Q1,Q2)+100. Both look like 2's in the scans but if zoomed the faint
outline of the 0's is barely visible, and in another scan of the book
(from annarchive.com) the 2's are clearly 0's.

The original source was in "crunched" format, while BBC BASIC can parse
code like that, I can't, so separated out the commands. With Microsoft
versions of BASIC, if the number for ON GOTO is out of range it just drops
through but that's an error in BBC BASIC so had to add range checks. Early
BASICs didn't mind if you jumped out of a FOR/NEXT loop but BBC BASIC uses
stacks to track loops and specifically warns against that. In the few
places it did that I converted the code to counters and GOTO statements.
Number prints in BBC BASIC do not add any extra spaces so that had to be
fixed and while at it fixed up some other text formatting things.
A subroutine for converting lowercase to uppercase was added,
so commands can be entered in lowercase or uppercase.

The computer mod was done so that just pressing Enter brings up the
help list instead of an empty string evaluating to 0 and bringing up
the cumulative record. Other minor mods have been made to the computer,
the record now has >204< etc marks to show your current location, and
the direction/distance calculator has been modified to show both the
units distance (what is entered into the NAV distance dialog) and the
actual distance (used for energy calculations). Here's the original...

PLEASE ENTER
  INITIAL COORDINATES (X,Y)? 8,6
  FINAL COORDINATES (X,Y)? 6,5
DIRECTION = 3.5
DISTANCE = 2.236068

...and the modified version...

PLEASE ENTER
  INITIAL COORDINATES: 8,6
    FINAL COORDINATES: 6,5
DIRECTION = 3.5
DISTANCE  = 2 UNITS (ACTUAL = 2.23606798)

For short distances it doesn't matter but when traveling long diagonal
distances using the original actual units will overshoot the target.

Also note that when navigating within a quadrant, each sector is a
distance of 0.125 units, not 0.1 since the quadrant is divided into 8x8
sectors, 1/8=0.125. For short distances 0.1 or 0.2 will move 1 or 2 sectors
but beyond that multiply the sector unit distance by 0.125 to get the correct fractional unit distance. This is a known bug in the Mark II computer (the
original Mark I computer did not have navigation aids), in particular the
starbase direction/distance calculator output is completely wrong as it
reuses the same calculation mathematics. However this system has been
installed for over 40 years and changing it might confuse existing users.
The UNITS mod was made as a compromise to assist in long distance voyages
without substantially altering the existing (rather fragile) mechanics.
Just multiply by 0.125 when navigating sectors and all will be well.

Three new commands have been added...

 SAE - Save And Exit. This command saves the current game to
       the file SST3SAVE.DAT and exits. When the program runs,
       if the save file exits then it prompts to load it then
       continues from the saved point. The save file is deleted
       when the game completes or is aborted with the XXX command.
       
 STO - Stop program execution. Useful for editing the code from within
       the interpreter under Android where the mechanism for triggering
       Esc also makes the keyboard go away and, at least on my phone,
       quite hard to get back. At the > prompt you can RUN to restart,
       QUIT to exit the interpreter, or enter the GOTO that was printed
       to continue the game.
       
 SET - Set Options. Lets you select monochrome or color, choose between
       four different SRS display formats, select what happens when the
       program exits, and select what happens when an error occurs
       including when Esc is pressed. After entering the preferences
       it prompts to save them, if confirmed the settings are saved to
       the file SST3PREF.DAT. Afterwards the game continues with the
       new settings.

This is the default GRID look...

COMBAT AREA      CONDITION RED
 ___ ___ ___ ___ ___ ___ ___ ___
|___|___|_*_|___|___|___|___|_*_|       STARDATE           3720.3
|___|___|___|___|___|___|___|___|       CONDITION          *RED*
|___|___|_B_|___|___|_*_|___|_E_|       QUADRANT           2,8
|___|___|___|___|___|___|___|_K_|       SECTOR             3,8
|___|___|___|___|_*_|___|___|___|       PHOTON TORPEDOES   4
|___|___|___|___|___|___|___|___|       TOTAL ENERGY       775
|___|___|___|___|___|___|___|___|       SHIELDS            400
|___|___|___|___|___|___|___|_*_|       KLINGONS REMAINING 6

COMMAND: 

This is the STOCK look...

COMBAT AREA      CONDITION RED
---------------------------------
          *                   *         STARDATE           3720.3
                                        CONDITION          *RED*
         >!<          *      <*>        QUADRANT           2,8
                             +K+        SECTOR             3,8
                  *                     PHOTON TORPEDOES   4
                                        TOTAL ENERGY       775
                                        SHIELDS            400
                              *         KLINGONS REMAINING 6
---------------------------------
COMMAND: 

This is the DOTS look...

COMBAT AREA      CONDITION RED
---------------------------------
  .   .   *   .   .   .   .   *         STARDATE           3720.3
  .   .   .   .   .   .   .   .         CONDITION          *RED*
  .   .  >!<  .   .   *   .  <*>        QUADRANT           2,8
  .   .   .   .   .   .   .  +K+        SECTOR             3,8
  .   .   .   .   *   .   .   .         PHOTON TORPEDOES   4
  .   .   .   .   .   .   .   .         TOTAL ENERGY       775
  .   .   .   .   .   .   .   .         SHIELDS            400
  .   .   .   .   .   .   .   *         KLINGONS REMAINING 6
---------------------------------
COMMAND: 

This is the DIV1 setting...

COMBAT AREA      CONDITION RED
---- --- --- --- --- --- --- ----
          *                   *         STARDATE           3720.3
                                        CONDITION          *RED*
         >!<          *      <*>        QUADRANT           2,8
                             +K+        SECTOR             3,8
                  *                     PHOTON TORPEDOES   4
                                        TOTAL ENERGY       775
                                        SHIELDS            400
                              *         KLINGONS REMAINING 6
---- --- --- --- --- --- --- ----
COMMAND: 

This is the DIV2 setting...

COMBAT AREA      CONDITION RED
--=---=---=---=---=---=---=---=--
          *                   *         STARDATE           3720.3
                                        CONDITION          *RED*
         >!<          *      <*>        QUADRANT           2,8
                             +K+        SECTOR             3,8
                  *                     PHOTON TORPEDOES   4
                                        TOTAL ENERGY       775
                                        SHIELDS            400
                              *         KLINGONS REMAINING 6
--=---=---=---=---=---=---=---=--
COMMAND: 

The display can be monochrome (like the original) or colorized.
For monochrome you can enter codes for the forground and background.
The colors are 1=black 2=red 3=yellow 4=blue 5=magenta 6=cyan and 7=white.
Add 8 to the color code for bright. When set to color the background is
black and various items are colored for severity and just to look ok -
good things are green, status reports are cyan, bad things are red or
magenta, warnings are yellow, etc but it's not always consistent. Variables
are used for the color codes so it's easy to modify for other color schemes.

The ON EXIT setting determines what happens when the program exits,
QUIT (the default) exits the interpreter and closes the window, END makes
it drop to the interpreter > prompt. When running under Android a TOUCHIDE
option is also available, this causes it to exit by running the touchide.bbc
program that's included with the BBC BASIC package.

The ON ERROR/ESC setting determines what happens if an error occurs or
the Esc key is pressed.. END (the default) makes it drop to the > prompt
with an error report, and EXIT makes it exit however ON EXIT is set.

The location for the save and preference files is BBC BASIC's @usr$ (user)
directory, where exactly that is depends on the platform. On my system the
Linux version of BBC BASIC for SDL uses $HOME/.local/share/BBCBasic and
BBC Basic for Windows uses /users/[name]/MyDocuments (at least under wine).
To change the save directory change the SDIR variable on line 9, the choices
are 0 for the current directory, 1 for @usr$ (the default), 2 for @dir$
to use the program directory even if it's not the current directory,
and 3 for @tmp$, BBC BASIC's temp directory.

If running under the console version of Matrix Brandy the save/preference
files are saved to the current directory as this version of BBC BASIC does
not have variables for pre-defined directories, and because the file format
is different, the files are named SST3BRSAVE.DAT and SST3BRPREF.DAT.


Legal Stuff
-----------

"Star Trek" and its characters are registered trademarks of Paramount
Pictures and/or Paramount Studios Inc. and most recently CBS Studios Inc.
The trademark owners do not endorse and are not affiliated with the SST3
program in any way. The SST3 program is not intended for commercial use
of any kind, including distributing on websites with intentional ads.
If you feel that you must make a commercial version of this (I know it's
an awesome concept! Some companies have sold versions of it) then you
should either scrub the code of any mentions of Star Trek and its
characters, or obtain permission from the current trademark holder(s).

Trademarks aside, the SST3 code was derived from code that was freely
distributed as far back as 1973 and worked on many people before it was
published in 1978. It is presumed to be public domain and I do not claim
any copyright on my changes, do whatever you want to do with this code.
This software and related material is provided as-is and without warranty,
use at your own risk.

The executable SST3.exe file contains code that was produced by BBC BASIC
for Windows version 6.13a, Copyright (C) R. T. Russell 2001-2020. The docs
state "You can distribute such executables freely without any royalty for
BBC BASIC being due". The full compiler is awesome and is available for
purchase at: https://www.bbcbasic.co.uk/bbcwin/bbcwin.html

That leaves these docs.. on that it's fairly specific to this particular
release archive but if creating derivative versions etc feel free to pull
out what you need. I'm pretty sure it's ok to redistribute this zip file
for non-commercial purposes but if you do, you are on your own, and I
specifically disclaim responsibility for anything I did not do myself.


Change log
----------

The SST3 program itself has been modified numerous times since it started
life as the monochrome SST2 BBC BASIC translation I did in August 2020.
Refer to the source code for these changes. The following is a change log
for this release archive.

February 22, 2021 - initial release of SST3.bas SST3.bbc and SST3.exe

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

These docs last modified Feb 22, 2021
Terry Newton (wtn90125@yahoo.com)


