This is the hackers' guide to SST2K. Read it before messing with the code.
It consists of an introduction, a history, suggestions for regression testing,
-some notes on the Python translation. For a to-do list, see TODO in the
+and some notes on the Python translation. For a to-do list, see TODO in the
top-level directory.
INTRODUCTION:
to; otherwise they die in space and this counts heavily against
your score. Docking at a starbase replenishes your crew.
-8. Still more BSD-Trek: we now have a weighted damage table.
+8. Still more BSD-Trek: we now have a weighted damage table. Quoth
+Eric Allman in the code of BSD-Trek: "Under certain conditions you can
+get a critical hit. This sort of hit damages devices. The
+probability that a given device is damaged depends on the device.
+Well protected devices (such as the computer, which is in the core of
+the ship and has considerable redundancy) almost never get damaged,
+whereas devices which are exposed (such as the warp engines) or which
+are particularly delicate (such as the transporter) have a much higher
+probability of being damaged."
+
+This is one place where OPTION_PLAIN does not restore the original
+behavior, which was equiprobable damage across all devices. If we
+wanted that, we'd return randrange(NDEVICES) and have done with it.
+Also, in the original game, DNAVSYS and DCOMPTR were the same device.
+
+Instead, we use a table of weights similar to the one from BSD Trek.
+BSD doesn't have the shuttle, shield controller, death ray, or probes.
+We don't have a cloaking device. The shuttle got the allocation for
+the cloaking device, then we shaved a half-percent off everything to
+have some weight to give DSHCTRL/DDRAY/DDSP.
+
Also, the nav subsystem (enabling automatic course
setting) can be damaged separately from the main computer (which
handles weapons targeting, ETA calculation, and self-destruct).
-After these features were added, I translated this into Python and added
-more:
+After these features were added, I translated this program into Python
+and added more:
9. A long-range scan is done silently whenever you call CHART; thus
the LRSCAN command is no longer needed. (Controlled by OPTION_AUTOSCAN
and turned off if game type is "plain" or "almy".)
+10. I imported Tom Almy's SCORE, CAPTURE, and CLOAK command from his
+2013 version.
+
+11. I added color.
+
TESTING:
This code has been designed to be tested. A simple shellscript
included in the distribution, 'replay', automatically reruns the
last game you played.
-Here are some interesting seeds for debugging and regression testing
-For each one, I list the seed, the options, and the last svn revision
-for which it is known to have given the described behavior.
+See the "test" directory for regression-test logs and checkfiles.
+Please run 'make check' every time you change this game to be sure
+you haven't broken anything.
-1160647745 regular short good fancy (r769)
+When you fix a bug, add the log of the game that triggered it (and
+a checkfile) to the regression tests. This is how we improve the code
+coverage of the suite.
-Starts you in a quadrant with the Super-Commander in it. Slamming three
-torps at him will kill him. You can use this to regression-test both
-torpedo tracks and the Deep Space Probe. Known bug: "probe aut 2 8"
-triggers manual navigation.
+Two things to do to the log before dropping it in the test directory:
-1160707235 regular short good fancy (r769)
+(a) Strip out all lines beginning with "#curses:" - these are for debugging
+the curses interface and are not needed or regression testing; removing
+them makes it easier to see the game commands.
-Do sr/mov aut 5 4/sr/sensors/orbit/transport; you'll get a transporter
-failure.
+(b) Add a header comment line explaining what the log is a test for.
+It should begin with "# Tests". This is what gets echoed before each
+regression test is run.
+
+Then drop it into the test directory and "make buildregress" to create
+the check file. (Don't forget to commit and push the log and checkfile
+to the repository.)
NOTES ON THE PYTHON TRANSLATION:
The LOC count dropped by almost exactly 20% during this process, from
a bit over 8100 lines to a bit over 6500 lines. If the code is still
-shorter than that when you read thism, it's because this file comtains
-nost of what used to be a huge header comment.
+shorter than that when you read this, it's because this file contains
+most of what used to be a huge header comment.
SST is not a data-structure- intensive program, so it compresses less
under translation to Python than the 50% drop in LOC I've found to be
in C, I introduced a struct; in Python, the class has a complete
repertoire of vector-algebra operations.
+There's one weird archeological detail about the nav code that
+deserves a remark. This program originally required input in terms of
+a (clock) direction and distance -- essentially, directions were real
+numbers modulo 12 with zero being north. Somewhere in history, it was
+changed to Cartesian coordinates. But the bearing method still computes
+polar coordinates in clockface units -- that's the reason for the
+wacky constant 1.90985, inherited straight from the ancestral FORTRAN.
+Elsewhere, there were a bunch of computations, now centralized in the
+course object, that looked like (15.0 - bearing)*0.5235988; this is a
+conversion from clockface units to radians with zero on the X axis.
+
+As a previous maintainer, probably Tom Almy, observed: Probably
+"manual" input should still be done this way -- it's a real pain if
+the computer isn't working! Manual mode is still confusing because it
+involves giving x and y motions, yet the coordinates are always
+displayed y - x, where +y is downward!
+
+Because I think he's arguably right, I haven't ripped out all the
+clockface-to-radian conversions. For this reason, and others, the
+trig code is still a bit wacky and obscure. Modify with caution
+and test thoroughly.
+