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 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. (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.)
47 The Faerie Queen, black holes, and time warping were in the original.
49 Here are Tom Almy's changes:
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.
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.)
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".)
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.
80 4. Tholian Web from the 1979 version. (Now controlled by
81 OPTION_THOLIAN and turned off if game type is "plain".)
83 5. Enemies can ram the Enterprise. (Now controlled by OPTION_RAMMING
84 and turned off if game type is "plain".)
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".)
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").
93 8. 'emexit' command from the 1979 version.
95 9. Bugfix: Klingon commander movements are no longer reported if long-range
98 10. Bugfix: Better base positioning at startup (more spread out).
99 That made sense to add because most people abort games with
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.)
108 Here are Stas Sergeev's changes:
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".)
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".)
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".)
124 4. The Tholian can be hit with phasers.
126 5. SCom can't escape from you if no more enemies remain
127 (without this, chasing SCom can take an eternity).
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.
132 7. Secret password is now autogenerated.
134 8. "Plaque" is adjusted for A4 paper :-)
136 9. Phasers now tells you how much energy needed, but only if the computer
139 10. Planets are auto-scanned when you enter the quadrant.
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
145 12. "freeze" command reverts to "save", most people will understand this
146 better anyway. (SST2K recognizes both.)
148 13. Screen-oriented interface, with sensor scans always up. (SST2K
149 supports both screen-oriented and TTY modes.)
151 Eric Raymond's changes:
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.
156 1. "sos" and "call" becomes "mayday", "freeze" and "save" are both good.
158 2. Status report now indicates when dilithium crystals are on board.
160 3. Per Dave Matuszek's remarks, Thingy state is never saved across games.
162 4. Added game option selection so you can play a close (but not bug-for-
163 bug identical) approximation of older versions.
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".)
173 6. User input is now logged so we can do regression testing.
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.
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).
186 After these features were added, I translated this into Python and added
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".)
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.
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.
203 1160647745 regular short good fancy (r769)
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.
210 1160707235 regular short good fancy (r769)
212 Do sr/mov aut 5 4/sr/sensors/orbit/transport; you'll get a transporter
215 NOTES ON THE PYTHON TRANSLATION:
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.
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.
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.
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.
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.
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.
248 There's one weird archeological detail about the nav code that
249 deserves a remark. This program originally required input in terms of
250 a (clock) direction and distance -- essentially, directions were real
251 numbers modulo 12 with zero being north. Somewhere in history, it was
252 changed to Cartesian coordinates. But the bearing method still computes
253 polar coordinates in clockface units -- that's the reason for the
254 wacky constant 1.90985, inherited straight from the ancestral FORTRAN.
255 Elsewhere, there were a bunch of computations, now centralized in the
256 course object, that looked like (15.0 - bearing)*0.5235988; this is a
257 conversion from clockface units to radians with zero on the X axis.
259 As a previous maintainer, probably Tom Almy, observed: Probably
260 "manual" input should still be done this way -- it's a real pain if
261 the computer isn't working! Manual mode is still confusing because it
262 involves giving x and y motions, yet the coordinates are always
263 displayed y - x, where +y is downward!
265 Because I think he's arguably right, I haven't ripped out all the
266 clockface-to-radian conversions. For this reason, and others, the
267 trig code is still a bit wacky and obscure. Modify with caution