doc/HACKING

   1 This is the hackers' guide to SST2K.  Read it before messing with the code.
   2
   3 It consists of an introduction, a history, suggestions for regression testing,
   4 some notes on the Python translation.  For a to-do list, see TODO in the
   5 top-level directory.
   6
   7 INTRODUCTION:
   8
   9 SST2K is a Python translation of a C translation of a FORTRAN
  10 original dating back to 1973.  Beautiful Python it is not, but it
  11 works.
  12
  13 The intention of SST2K is to be able to replicate precisely the
  14 experience of the original game, while allowing new features to be
  15 added under option control.  Therefore, be very conservative about
  16 what changes are visible under the 'plain' option.
  17
  18 HISTORY:
  19
  20 Dave Matuszek, one of the two original authors, says:
  21
  22 SRSCAN, MOVE, PHASERS, CALL, STATUS, IMPULSE, PHOTONS, ABANDON,
  23 LRSCAN, WARP, SHIELDS, DESTRUCT, CHART, REST, DOCK, QUIT, and DAMAGE
  24 were in the original non-"super" version of UT FORTRAN Star Trek.
  25
  26 Tholians were not in the original. Dave is dubious about their merits.
  27 (They are now controlled by OPTION_THOLIAN and turned off if the game
  28 type is "plain".)
  29
  30 Planets and dilithium crystals were not in the original.  Dave is OK
  31 with this idea. (It's now controlled by OPTION_PLANETS and turned
  32 off if the game type is "plain".)
  33
  34 Dave says the bit about the Galileo getting turned into a
  35 McDonald's is "consistant with our original vision".  (This has been
  36 left permanently enabled, as it can only happen if OPTION_PLANETS
  37 is on.)
  38
  39 Dave also says the Space Thingy should not be preserved across saved
  40 games, so you can't prove to others that you've seen it.  He says it
  41 shouldn't fire back, either.  It should do nothing except scream and
  42 disappear when hit by photon torpedos.  It's OK that it may move
  43 when attacked, but it didn't in the original.  (Whether the Thingy
  44 can fire back is now controlled by OPTION_THINGY and turned off if the
  45 game type is "plain" or "almy".  The no-save behavior has been restored.)
  46
  47 The Faerie Queen, black holes, and time warping were in the original.
  48
  49 Here are Tom Almy's changes:
  50
  51 In early 1997, I got the bright idea to look for references to
  52 "Super Star Trek" on the World Wide Web. There weren't many hits,
  53 but there was one that came up with 1979 Fortran sources! This
  54 version had a few additional features that mine didn't have,
  55 however mine had some feature it didn't have. So I merged its
  56 features that I liked. I also took a peek at the DECUS version (a
  57 port, less sources, to the PDP-10), and some other variations.
  58
  59 1, Compared to the original UT version, I've changed the "help"
  60 command to "call" and the "terminate" command to "quit" to better
  61 match user expectations. The DECUS version apparently made those
  62 changes as well as changing "freeze" to "save". However I like
  63 "freeze".  (Both "freeze" and "save" work in SST2K.)
  64
  65 2. The experimental deathray originally had only a 5% chance of
  66 success, but could be used repeatedly. I guess after a couple
  67 years of use, it was less "experimental" because the 1979
  68 version had a 70% success rate. However it was prone to breaking
  69 after use. I upgraded the deathray, but kept the original set of
  70 failure modes (great humor!).  (Now controlled by OPTION_DEATHRAY
  71 and turned off if game type is "plain".)
  72
  73 3. The 1979 version also mentions srscan and lrscan working when
  74 docked (using the starbase's scanners), so I made some changes here
  75 to do this (and indicating that fact to the player), and then realized
  76 the base would have a subspace radio as well -- doing a Chart when docked
  77 updates the star chart, and all radio reports will be heard. The Dock
  78 command will also give a report if a base is under attack.
  79
  80 4. Tholian Web from the 1979 version.  (Now controlled by
  81 OPTION_THOLIAN and turned off if game type is "plain".)
  82
  83 5. Enemies can ram the Enterprise. (Now controlled by OPTION_RAMMING
  84 and turned off if game type is "plain".)
  85
  86 6. Regular Klingons and Romulans can move in Expert and Emeritus games.
  87 This code could use improvement. (Now controlled by OPTION_MVBADDY
  88 and turned off if game type is "plain".)
  89
  90 7. The deep-space probe feature from the DECUS version.  (Now controlled
  91 by OPTION_PROBE and turned off if game type is "plain").
  92
  93 8. 'emexit' command from the 1979 version.
  94
  95 9. Bugfix: Klingon commander movements are no longer reported if long-range
  96 sensors are damaged.
  97
  98 10. Bugfix: Better base positioning at startup (more spread out).
  99 That made sense to add because most people abort games with
 100 bad base placement.
 101
 102 In June 2002, I fixed two known bugs and a documentation typo.
 103 In June 2004 I fixed a number of bugs involving: 1) parsing invalid
 104 numbers, 2) manual phasers when SR scan is damaged and commander is
 105 present, 3) time warping into the future, 4) hang when moving
 106 klingons in crowded quadrants.  (These fixes are in SST2K.)
 107
 108 Here are Stas Sergeev's changes:
 109
 110 1. The Space Thingy can be shoved, if you ram it, and can fire back if
 111 fired upon. (Now controlled by OPTION_THINGY and turned off if game
 112 type is "plain" or "almy".)
 113
 114 2. When you are docked, base covers you with an almost invincible shield.
 115 (A commander can still ram you, or a Romulan can destroy the base,
 116 or a SCom can even succeed with direct attack IIRC, but this rarely
 117 happens.)  (Now controlled by OPTION_BASE and turned off if game
 118 type is "plain" or "almy".)
 119
 120 3. Ramming a black hole is no longer instant death.  There is a
 121 chance you might get timewarped instead. (Now controlled by
 122 OPTION_BLKHOLE and turned off if game type is "plain" or "almy".)
 123
 124 4. The Tholian can be hit with phasers.
 125
 126 5. SCom can't escape from you if no more enemies remain
 127 (without this, chasing SCom can take an eternity).
 128
 129 6. Probe target you enter is now the destination quadrant. Before I don't
 130 remember what it was, but it was something I had difficulty using.
 131
 132 7. Secret password is now autogenerated.
 133
 134 8. "Plaque" is adjusted for A4 paper :-)
 135
 136 9. Phasers now tells you how much energy needed, but only if the computer
 137 is alive.
 138
 139 10. Planets are auto-scanned when you enter the quadrant.
 140
 141 11. Mining or using crystals in presense of enemy now yields an attack.
 142 There are other minor adjustments to what yields an attack
 143 and what does not.
 144
 145 12. "freeze" command reverts to "save", most people will understand this
 146 better anyway. (SST2K recognizes both.)
 147
 148 13. Screen-oriented interface, with sensor scans always up.  (SST2K
 149 supports both screen-oriented and TTY modes.)
 150
 151 Eric Raymond's changes:
 152
 153 Mainly, I translated this C code out of FORTRAN into C -- created #defines
 154 for a lot of magic numbers and refactored the heck out of it.
 155
 156 1. "sos" and "call" becomes "mayday", "freeze" and "save" are both good.
 157
 158 2. Status report now indicates when dilithium crystals are on board.
 159
 160 3. Per Dave Matuszek's remarks, Thingy state is never saved across games.
 161
 162 4. Added game option selection so you can play a close (but not bug-for-
 163 bug identical) approximation of older versions.
 164
 165 5. Half the quadrants now have inhabited planets, from which one
 166 cannot mine dilithium (there will still be the same additional number
 167 of dilithium-bearing planets).  Torpedoing an inhabited world is *bad*.
 168 There is BSD-Trek-like logic for Klingons to attack and enslave
 169 inhabited worlds, producing more ships (only is skill is 'good' or
 170 better). (Controlled by OPTION_WORLDS and turned off if game
 171 type is "plain" or "almy".)
 172
 173 6. User input is now logged so we can do regression testing.
 174
 175 7. More BSD-Trek features: You can now lose if your entire crew
 176 dies in battle.  When abandoning ship in a game with inhabited
 177 worlds enabled, they must have one in the quadrant to beam down
 178 to; otherwise they die in space and this counts heavily against
 179 your score.  Docking at a starbase replenishes your crew.
 180
 181 8. Still more BSD-Trek: we now have a weighted damage table.
 182 Also, the nav subsystem (enabling automatic course
 183 setting) can be damaged separately from the main computer (which
 184 handles weapons targeting, ETA calculation, and self-destruct).
 185
 186 After these features were added, I translated this into Python and added
 187 more:
 188
 189 9. A long-range scan is done silently whenever you call CHART; thus
 190 the LRSCAN command is no longer needed.  (Controlled by OPTION_AUTOSCAN
 191 and turned off if game type is "plain" or "almy".)
 192
 193 TESTING:
 194
 195 This code has been designed to be tested.  A simple shellscript
 196 included in the distribution, 'replay', automatically reruns the
 197 last game you played.
 198
 199 Here are some interesting seeds for debugging and regression testing
 200 For each one, I list the seed, the options, and the last svn revision
 201 for which it is known to have given the described behavior.
 202
 203 1160647745 regular short good fancy     (r769)
 204
 205 Starts you in a quadrant with the Super-Commander in it.  Slamming three
 206 torps at him will kill him.  You can use this to regression-test both
 207 torpedo tracks and the Deep Space Probe. Known bug: "probe aut 2 8"
 208 triggers manual navigation.
 209
 210 1160707235 regular short good fancy     (r769)
 211
 212 Do sr/mov aut 5 4/sr/sensors/orbit/transport; you'll get a transporter
 213 failure.
 214
 215 NOTES ON THE PYTHON TRANSLATION:
 216
 217 The Python translation was done with a regexp-based C-to-Python
 218 translator I wrote for the purpose (I expect to release this as a
 219 separate project).  I then hand-tuned and refactored the result.
 220
 221 The LOC count dropped by almost exactly 20% during this process, from
 222 a bit over 8100 lines to a bit over 6500 lines.  If the code is still
 223 shorter than that when you read thism, it's because this file comtains
 224 nost of what used to be a huge header comment.
 225
 226 SST is not a data-structure- intensive program, so it compresses less
 227 under translation to Python than the 50% drop in LOC I've found to be
 228 more typical.  The gain in readability, though impossible to quantify,
 229 is much greater than the drop in line count would suggest.
 230
 231 Some parts of the code, such as the finish() and score() functions,
 232 have barely been touched.  Code in the general category of report
 233 generators has tended to change little, especially since we've tried
 234 to preserve the look and feel of the original.
 235
 236 On the other hand, the vector-arithmetic code around navigation and
 237 torpedos, and deep-space-probe handling changed a lot.  All that
 238 stuff is now centralized in a 'course' object that hides the
 239 trigonometric calculations.
 240
 241 The course object builds on a 'coord' object, which I actually had
 242 introduced while refactoring the C version.  Large parts of SST2K are,
 243 perforce, an exercise in 2D vector arithmetic.  In the original
 244 FORTRAN all the vector representation was done with parallel arrays;
 245 in C, I introduced a struct; in Python, the class has a complete
 246 repertoire of vector-algebra operations.
 247