X-Git-Url: https://jxself.org/git/?p=super-star-trek.git;a=blobdiff_plain;f=doc%2FHACKING;h=46c35425f41eb06a3da5be3898fabcfc5c07e8b3;hp=1cef4b4edc3d1f38338f57f01dc0ad5338caae9e;hb=3940e6e663a29090fb77fe639a8f49d1a3c999d1;hpb=6f4f98ea41c6c792d99bceb2618c659ead349c08

diff --git a/doc/HACKING b/doc/HACKING
index 1cef4b4..46c3542 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:
@@ -178,13 +178,33 @@ 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
@@ -196,21 +216,13 @@ 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.
-
-1160647745 regular short good fancy	(r769)
-
-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.
-
-1160707235 regular short good fancy	(r769)
+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.  
 
-Do sr/mov aut 5 4/sr/sensors/orbit/transport; you'll get a transporter
-failure.
+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.
 
 NOTES ON THE PYTHON TRANSLATION:
 
@@ -220,8 +232,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