1 This is the hackers' guide to SST2K. Read it before messing with the code.
3 It consists of an introduction, a history, suggestions for regression testing,
4 and some notes on the Python translation. For a to-do list, see TODO in the
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
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.
20 Dave Matuszek, one of the two original authors, says:
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.
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
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".)
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
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. (The no-save behavior
46 The Faerie Queen, black holes, and time warping were in the original.
48 Here are Tom Almy's changes:
50 In early 1997, I got the bright idea to look for references to
51 "Super Star Trek" on the World Wide Web. There weren't many hits,
52 but there was one that came up with 1979 Fortran sources! This
53 version had a few additional features that mine didn't have,
54 however mine had some feature it didn't have. So I merged its
55 features that I liked. I also took a peek at the DECUS version (a
56 port, less sources, to the PDP-10), and some other variations.
58 1. Compared to the original UT version, I've changed the "help"
59 command to "call" and the "terminate" command to "quit" to better
60 match user expectations. The DECUS version apparently made those
61 changes as well as changing "freeze" to "save". However I like
62 "freeze". (Both "freeze" and "save" work in SST2K.)
64 2. The experimental deathray originally had only a 5% chance of
65 success, but could be used repeatedly. I guess after a couple
66 years of use, it was less "experimental" because the 1979
67 version had a 70% success rate. However it was prone to breaking
68 after use. I upgraded the deathray, but kept the original set of
69 failure modes (great humor!). (Now controlled by OPTION_DEATHRAY
70 and turned off if game type is "plain".)
72 3. The 1979 version also mentions srscan and lrscan working when
73 docked (using the starbase's scanners), so I made some changes here
74 to do this (and indicating that fact to the player), and then realized
75 the base would have a subspace radio as well -- doing a Chart when docked
76 updates the star chart, and all radio reports will be heard. The Dock
77 command will also give a report if a base is under attack.
79 4. Tholian Web from the 1979 version. (Now controlled by
80 OPTION_THOLIAN and turned off if game type is "plain".)
82 5. Enemies can ram the Enterprise. (Now controlled by OPTION_RAMMING
83 and turned off if game type is "plain".)
85 6. Regular Klingons and Romulans can move in Expert and Emeritus games.
86 This code could use improvement. (Now controlled by OPTION_MVBADDY
87 and turned off if game type is "plain".)
89 7. The deep-space probe feature from the DECUS version. (Now controlled
90 by OPTION_PROBE and turned off if game type is "plain").
92 8. 'emexit' command from the 1979 version.
94 9. Bugfix: Klingon commander movements are no longer reported if long-range
97 10. Bugfix: Better base positioning at startup (more spread out).
98 That made sense to add because most people abort games with
101 In June 2002, I fixed two known bugs and a documentation typo.
102 In June 2004 I fixed a number of bugs involving: 1) parsing invalid
103 numbers, 2) manual phasers when SR scan is damaged and commander is
104 present, 3) time warping into the future, 4) hang when moving
105 klingons in crowded quadrants. (These fixes are in SST2K.)
107 Here are Stas Sergeev's changes:
109 1. The Space Thingy can be shoved, if you ram it, and can fire back if
110 fired upon. (Now controlled by OPTION_THINGY and turned off if game
111 type is "plain" or "almy".)
113 2. When you are docked, base covers you with an almost invincible shield.
114 (A commander can still ram you, or a Romulan can destroy the base,
115 or a SCom can even succeed with direct attack IIRC, but this rarely
116 happens.) (Now controlled by OPTION_BASE and turned off if game
117 type is "plain" or "almy".)
119 3. Ramming a black hole is no longer instant death. There is a
120 chance you might get timewarped instead. (Now controlled by
121 OPTION_BLKHOLE and turned off if game type is "plain" or "almy".)
123 4. The Tholian can be hit with phasers.
125 5. SCom can't escape from you if no more enemies remain
126 (without this, chasing SCom can take an eternity).
128 6. Probe target you enter is now the destination quadrant. Before I don't
129 remember what it was, but it was something I had difficulty using.
131 7. Secret password is now autogenerated.
133 8. "Plaque" is adjusted for A4 paper :-)
135 9. Phasers now tells you how much energy needed, but only if the computer
138 10. Planets are auto-scanned when you enter the quadrant.
140 11. Mining or using crystals in presense of enemy now yields an attack.
141 There are other minor adjustments to what yields an attack
144 12. "freeze" command reverts to "save", most people will understand this
145 better anyway. (SST2K recognizes both.)
147 13. Screen-oriented interface, with sensor scans always up. (SST2K
148 supports both screen-oriented and TTY modes.)
150 Eric Raymond's changes:
152 Mainly, I translated this C code out of FORTRAN into C -- created #defines
153 for a lot of magic numbers and refactored the heck out of it.
155 1. "sos" and "call" becomes "mayday", "freeze" and "save" are both good.
157 2. Status report now indicates when dilithium crystals are on board.
159 3. Per Dave Matuszek's remarks, Thingy state is never saved across games.
161 4. Added game option selection so you can play a close (but not bug-for-
162 bug identical) approximation of older versions.
164 5. Half the quadrants now have inhabited planets, from which one
165 cannot mine dilithium (there will still be the same additional number
166 of dilithium-bearing planets). Torpedoing an inhabited world is *bad*.
167 There is BSD-Trek-like logic for Klingons to attack and enslave
168 inhabited worlds, producing more ships (only is skill is 'good' or
169 better). (Controlled by OPTION_WORLDS and turned off if game
170 type is "plain" or "almy".)
172 6. User input is now logged so we can do regression testing.
174 7. More BSD-Trek features: You can now lose if your entire crew
175 dies in battle. When abandoning ship in a game with inhabited
176 worlds enabled, they must have one in the quadrant to beam down
177 to; otherwise they die in space and this counts heavily against
178 your score. Docking at a starbase replenishes your crew.
180 8. Still more BSD-Trek: we now have a weighted damage table. Quoth
181 Eric Allman in the code of BSD-Trek: "Under certain conditions you can
182 get a critical hit. This sort of hit damages devices. The
183 probability that a given device is damaged depends on the device.
184 Well protected devices (such as the computer, which is in the core of
185 the ship and has considerable redundancy) almost never get damaged,
186 whereas devices which are exposed (such as the warp engines) or which
187 are particularly delicate (such as the transporter) have a much higher
188 probability of being damaged."
190 This is one place where OPTION_PLAIN does not restore the original
191 behavior, which was equiprobable damage across all devices. If we
192 wanted that, we'd return randrange(NDEVICES) and have done with it.
193 Also, in the original game, DNAVSYS and DCOMPTR were the same device.
195 Instead, we use a table of weights similar to the one from BSD Trek.
196 BSD doesn't have the shuttle, shield controller, death ray, or probes.
197 We don't have a cloaking device. The shuttle got the allocation for
198 the cloaking device, then we shaved a half-percent off everything to
199 have some weight to give DSHCTRL/DDRAY/DDSP.
201 Also, the nav subsystem (enabling automatic course
202 setting) can be damaged separately from the main computer (which
203 handles weapons targeting, ETA calculation, and self-destruct).
205 After these features were added, I translated this program into Python
208 9. A long-range scan is done silently whenever you call CHART; thus
209 the LRSCAN command is no longer needed. (Controlled by OPTION_AUTOSCAN
210 and turned off if game type is "plain" or "almy".)
212 10. I imported Tom Almy's SCORE, CAPTURE, and CLOAK command from his
219 This code has been designed to be tested. A simple shellscript
220 included in the distribution, 'replay', automatically reruns the
221 last game you played.
223 See the "test" directory for regression-test logs and checkfiles.
224 Please run 'make check' every time you change this game to be sure
225 you haven't broken anything.
227 When you fix a bug, add the log of the game that triggered it (and
228 a checkfile) to the regression tests. This is how we improve the code
229 coverage of the suite.
231 Two things to do to the log before dropping it in the test directory:
233 (a) Strip out all lines beginning with "#curses:" - these are for debugging
234 the curses interface and are not needed for regression testing; removing
235 them makes it easier to see the game commands.
237 (b) Add a header comment line explaining what the log is a test for.
238 It should begin with "# Tests". This is what gets echoed before each
239 regression test is run.
241 Then drop it into the test directory and "make buildregress" to create
242 the check file. (Don't forget to commit and push the log and checkfile
245 NOTES ON THE PYTHON TRANSLATION:
247 The Python translation was done with a regexp-based C-to-Python
248 translator I wrote for the purpose (I expect to release this as a
249 separate project). I then hand-tuned and refactored the result.
251 The LOC count dropped by almost exactly 20% during this process, from
252 a bit over 8100 lines to a bit over 6500 lines. If the code is still
253 shorter than that when you read this, it's because this file contains
254 most of what used to be a huge header comment.
256 SST is not a data-structure- intensive program, so it compresses less
257 under translation to Python than the 50% drop in LOC I've found to be
258 more typical. The gain in readability, though impossible to quantify,
259 is much greater than the drop in line count would suggest.
261 Some parts of the code, such as the finish() and score() functions,
262 have barely been touched. Code in the general category of report
263 generators has tended to change little, especially since we've tried
264 to preserve the look and feel of the original.
266 On the other hand, the vector-arithmetic code around navigation and
267 torpedos, and deep-space-probe handling changed a lot. All that
268 stuff is now centralized in a 'course' object that hides the
269 trigonometric calculations.
271 The course object builds on a 'coord' object, which I actually had
272 introduced while refactoring the C version. Large parts of SST2K are,
273 perforce, an exercise in 2D vector arithmetic. In the original
274 FORTRAN all the vector representation was done with parallel arrays;
275 in C, I introduced a struct; in Python, the class has a complete
276 repertoire of vector-algebra operations.
278 There's one weird archeological detail about the nav code that
279 deserves a remark. This program originally required input in terms of
280 a (clock) direction and distance -- essentially, directions were real
281 numbers modulo 12 with zero being north. Somewhere in history, it was
282 changed to Cartesian coordinates. But the bearing method still computes
283 polar coordinates in clockface units -- that's the reason for the
284 wacky constant 1.90985, inherited straight from the ancestral FORTRAN.
285 Elsewhere, there were a bunch of computations, now centralized in the
286 course object, that looked like (15.0 - bearing)*0.5235988; this is a
287 conversion from clockface units to radians with zero on the X axis.
289 As a previous maintainer, probably Tom Almy, observed: Probably
290 "manual" input should still be done this way -- it's a real pain if
291 the computer isn't working! Manual mode is still confusing because it
292 involves giving x and y motions, yet the coordinates are always
293 displayed y - x, where +y is downward!
295 Because I think he's arguably right, I haven't ripped out all the
296 clockface-to-radian conversions. For this reason, and others, the
297 trig code is still a bit wacky and obscure. Modify with caution