X-Git-Url: https://jxself.org/git/?p=super-star-trek.git;a=blobdiff_plain;f=doc%2FHACKING;h=133f72f6e84c9bbe93f7540252a2d9466978d175;hp=ef0ddb90e678a3deabd6156e9aa89ceeaf3759ad;hb=c8a6ef704e18389b06b0bbd5c755db606ac1c981;hpb=22f7cb3bfdf2e4759470f5decce4dba8c306e139

diff --git a/doc/HACKING b/doc/HACKING
index ef0ddb9..133f72f 100644
--- a/doc/HACKING
+++ b/doc/HACKING
@@ -1,7 +1,7 @@
 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:
@@ -56,7 +56,7 @@ however mine had some feature it didn't have. So I merged its
 features that I liked. I also took a peek at the DECUS version (a
 port, less sources, to the PDP-10), and some other variations.
 
-1, Compared to the original UT version, I've changed the "help"
+1. Compared to the original UT version, I've changed the "help"
 command to "call" and the "terminate" command to "quit" to better
 match user expectations. The DECUS version apparently made those
 changes as well as changing "freeze" to "save". However I like
@@ -178,39 +178,70 @@ worlds enabled, they must have one in the quadrant to beam down
 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:
 
@@ -220,8 +251,8 @@ separate project).  I then hand-tuned and refactored the result.
 
 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
@@ -245,3 +276,25 @@ FORTRAN all the vector representation was done with parallel arrays;
 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.
+