chiark / gitweb /
36c94a452f455b8a2ca013814d8b5ec799d594c7
[rocl] / README
1 RIGHT ON COMMAND-LINE
2   Elite tools for the discerning player
3
4 1. Installation
5
6         You need a C compiler and a working Tcl/Tk installation.  (The
7         elite-editor program needs Tk; the rest of the tools don't.)
8         The Makefile works on my Debian GNU/Linux box (potato), but I'm
9         not making any promises about anyone else's.  I've successfully
10         built earlier versions of everything under Cygwin, against
11         ActiveState's Tcl 8.4, but I've forgotten the Holy Runes.  I do
12         have the `.def' file I used to build the DLL, though, for
13         whatever that's worth.  (If you want to hack the Makefile to
14         work under Windows, I'll take a patch.)
15
16         The runes for Debian woody are:
17
18           $ make INCLUDES=/usr/include/tcl8.3
19           $ ROOTLY make install prefix=/usr
20
21         (where ROOTLY is some command which does things with root
22         privileges, say `sudo', `become root' or, at a pinch, `su -c')
23         because the Tcl installation no longer looks in /usr/local/lib,
24         worse luck.
25
26         The theory is that you should edit the Makefile for your system
27         and say `make'; then, as some suitably privileged person, say
28         `make install' and stand well back.  Everything should then be
29         installed.
30
31         In practice:
32
33           * If you can't build `pkgIndex.tcl', run `tclsh' and say
34
35               % pkg_mkIndex -verbose -direct -load Vec . \
36                 elite.so vec.so graph.so elite.tcl
37
38             to it.  (Use `elite.dll' etc. if you're on Windows.)  Say
39
40               % set tcl_pkgPath
41
42             to see a list of suitable places for putting the kit.  Pick
43             one.  The directory `/usr/local/lib' appears in my
44             installation, so that's what I use.
45
46           * Make a subdirectory in the place you chose, and copy
47             `elite.so', `elite.tcl' and `pkgIndex.tcl' into it.  All
48             should now be hunky-dory.
49
50           * Run (say) `elite-describe lave' to check that things are set
51             up properly.
52
53
54 2. The command-line tools
55
56         A `galaxy-spec' is
57
58           * a number, between 1 and 8, for one of the standard eight
59             galaxies; 
60
61           * a `galaxy seed' of 12 hex digits (a 48-bit value), for any
62             arbitrary galaxy; or
63
64           * a string `SEED:N' where SEED is a galaxy seed and N is a
65             number between 1 and 8, for the Nth galaxy in some custom
66             universe.
67
68         A `planet-spec' is interpreted relative to some parent galaxy.
69         It may be
70
71           * a number N, for the Nth planet in the galaxy (planets are
72             numbered pseudorandomly -- this is not often a helpful
73             option);
74
75           * a `planet seed' of 12 hex digits (a 48-bit value), for any
76             arbitrary planet;
77
78           * a pair of numbers `X,Y', for the planet nearest the point X
79             decilightyears rightwards and T decilightyears down from the
80             top left of the galaxy;
81
82           * a glob pattern (a string containing `*' and `?' wildcards,
83             matching any substring or any single character,
84             respectively), optionally followed by `/N' for some positive
85             integer N, for the Nth (default first) planet whose name
86             matches the pattern; or
87
88           * a string `GAL:P', where GAL is a galaxy-spec and P is a
89             planet-spec, for the planet P in galaxy GAL.
90
91
92   elite-describe [-g GAL] PLANET ...
93
94         For each PLANET, print the planet data for that PLANET.  The
95         PLANETs are interpreted relative to GAL, or standard galaxy 1 if
96         GAL is not specified.
97
98
99   elite-map [-qv] [-g GALAXY] [-d DIST] [-w WEIGHT] [-W WD,HT] [-a ASP]
100         [PLANET ...]
101
102         Prints a map of (part of) a galaxy to the terminal.
103
104         If PLANET is specified (which it usually is), a map of the area
105         around PLANET in GALAXY (default standard galaxy 1) is printed,
106         showing other planets within a box extending about DIST
107         lightyears around the PLANETs.
108
109         If no PLANETs are not specified, the entire galaxy is printed.
110         This is usually unhelpful.
111
112         The `-w' option plots a route through the listed planets,
113         highlighting the waypoints.  See `elite-path' for the possible
114         weightings.
115
116         Planets are shown as numbers or letters (or, occasionally a
117         sequence of letters).  If there is only one PLANET, it is shown
118         as a `*'; otherwise, they're labelled `*0', `*1', etc.  Planets
119         on the path are labelled `+0', `+1', ..., in the order you're
120         meant to visit them.  (Note that if the path doubles back on
121         itself, the planets involved /won't/ be listed twice.  Use
122         `elite-path' for a full guide on where to go, and `elite-map' to
123         visualize the route.)
124
125         The `-q' and `-v' options allow optional suppression of the key
126         below the map.  The defaults are as follows:
127
128           * A galactic map shows no key.
129
130           * A route map (with the `-w' option) shows the waypoints
131             (named PLANETs) and the planets on the path.
132
133           * An area map (around named planets) shows the names of all
134             planets shown.
135
136         The key can be made more verbose by giving the `-v' option, or
137         less verbose by `-q'.  Note that the options parser is currently
138         really shoddy, and won't let you say things like `-qqq'.
139
140         The size of the map may be controlled by the -W option -- set WD
141         to the maximum allowable width, and HT to the maximum allowable
142         height (in columns and rows, respectively).  The map will be
143         scaled so as to fit.  The -a option sets the aspect ratio of
144         your characters, height to width (the default is about 2, and
145         seems right for viewing in an xterm with the standard fixed
146         font).
147
148
149
150   elite-path [-g GALAXY] [-d DIST] [-w WEIGHT] [-a ACC] PLANET PLANET ...
151
152         Computes a route through a GALAXY (default is standard galaxy
153         1), starting at the first PLANET listed, via the second, via the
154         third, etc., and ending at the last.  For each planet you're
155         meant to stop at on the way, a summary line is printed giving
156         the planet's name, position, government type, economy type and
157         tech level.  The `-d' option gives the ship's hyperspace range
158         in lightyears.
159
160         You can affect how elite-path selects its routes using the `-w'
161         option.  The default is to minimize the number of hops.  Other
162         possibilities are:
163
164         hops            Minimize number of hops.  This is the default.
165
166         safety          Maximize stability of the planets in the route,
167                         to attempt to improve safety.  Useful during the
168                         early stages of the game.
169
170         encounters      The opposite of `safety' -- minimizes stability
171                         of planets in the route.  Useful if you want to
172                         maximize kills.
173
174         trading         Maximize the difference in economy type between
175                         successive planets in the route.  This should
176                         give you an opportunity to make a good profit as
177                         you go.
178
179         fuel            Minimize absolute distance.  For those on a
180                         tight budget.
181
182         The `-a' option controls what total is accumulated down the
183         right hand side of the summaries:
184
185         none            No running total down the right hand side.
186
187         distance        Accumulate distance, in lightyears.
188
189         weight          Accumulate the shortest-path weight function.
190
191         Beneath the path is printed a total for distance and weight if
192         these are interesting and not already displayed.  The weight for
193         `hops' and `fuel' are simply the hop count and distance in
194         lightyears respectively; the other weight functions use
195         appropriate square-law functions.
196
197
198   elite-reach [-d DIST] [GALAXY ...]
199
200         For each GALAXY (default is the 8 standard ones), print summary
201         information for each planet, with blank lines separating
202         disconnected groups of planets, i.e., groups where a ship
203         capable of travelling DIST lightyears (default 7) can't get from
204         one to the other.
205
206
207   elite-find [-g GALAXY] [EXPR]
208
209         Without EXPR, simply prints summary information for each planet
210         in GALAXY (default standard 1).
211
212         If EXPR is specified, it must be a Tcl expression (as for the
213         `expr' command).  Information is printed for each planet for
214         which EXPR returns nonzero.  The EXPR may use the following
215         variables:
216
217         name            The planet name, with initial capital letter.
218
219         x, y            X and Y coordinates, from top left, in
220                         decilightyears.
221
222         economy         From 0 (rich industrial) to 7 (poor
223                         agricultural).
224
225         government      From 0 (anarchy) to 7 (corporate state).
226
227         techlevel       From 1 to 15.
228
229         radius          In kilometres.
230
231         productivity    In millions of credits.
232
233         population      In hundreds of millions.
234
235         inhabitants     A Tcl list of words describing the inhabitants.
236
237         description     As a Tcl list of words.
238
239
240   elite-pairs [-g GALAXY] [-d DIST] AEXPR BEXPR
241
242         Prints the names of pairs of planets A and B in GALAXY (default
243         standard 1), no further than DIST (default 7) lightyears apart,
244         such that AEXPR returns nonzero for planet A and BEXPR returns
245         nonzero for planet B.
246
247         The expressions AEXPR and BEXPR may use the same variables as
248         for elite-find.  In addition, BEXPR may use
249
250         d               The distance between planets A and B.
251
252         a               An array containing the information about planet
253                         A.  The indices have the same names and meanings
254                         as the variables described above.
255
256
257   elite-cmdr [FILE] [-OPTION | ATTR | ATTR=VALUE | FILE] ...
258
259         A command-line Elite commander editor and viewer.  With a single
260         argument, reads a commander file and displays its contents as a
261         human readable table.  The arguments may be special options,
262         attribute names, attribute assignments, or filenames.
263
264         The special options are:
265
266         -show           Write the commander data to standard output as a
267                         human-readable table.  This is the default if no
268                         other output action is requested.
269
270         -load FILE      Read the commander file named FILE.
271
272         -save FILE      Write the modified commander data to FILE.
273
274         -reset          Reset the commander to the default `JAMESON'
275                         settings.
276
277         -dump           Write the commander data to standard output in
278                         the form of a script which can be read back by
279                         the `-read' option.
280
281         -read FILE      Read attribute/value pairs from FILE, and modify
282                         the commander accordingly.
283
284         An attribute name on its own is a request to print the current
285         value of that attribute.  An assignment ATTR=VALUE makes ATTR
286         have the requested VALUE.  When requesting attributes, you can
287         instead give a pattern containing `*' and `?' metacharacters
288         (matching zero or more, or exactly one character) -- all
289         matching attributes are printed.
290
291         The attributes, their meanings, and the acceptable values are as
292         follows:
293
294         mission         The commander's current mission.  (0 is no
295                         mission; 1 is searching for the Constrictor; 2
296                         is killed the Constrictor; 3 is waiting for the
297                         second mission; 4 is heading for Ceerdi; 5 is
298                         heading for Birera; and 6 is all missions
299                         completed.)  Must be an integer between 0 and
300                         255.
301
302         score           Current number of kills.  Must be an integer
303                         between 0 and 65535, or one of the strings
304                         `harmless', `mostly-harmless', `poor',
305                         `average', `above-average', `competent',
306                         `dangerous', `deadly', or `elite'.
307
308         legal-status    Current legal status.  Must be an integer
309                         between 0 and 255, or one of the strings
310                         `clean', `offender', or `fugitive'.
311
312         credits         Number of credits.  Must be between 0 and
313                         429496729.5.
314
315         cargo           Size of cargo bay.  Must be between 4 and 255.
316
317         gal-number      Number of the current galaxy.  Note that this
318                         doesn't affect which galaxy the commander is
319                         actually in -- set gal-seed for that.  Must be
320                         between 1 and 8.
321
322         gal-seed        Which galaxy the commander is in.  May be any
323                         galaxy-spec.
324
325         world           Which world the commander is docked at.  May be
326                         any planet-spec describing a world in the
327                         correct galaxy.  (Note that, since the commander
328                         file actually stores the location as an x, y
329                         pair and chooses the closest world to those
330                         coordinates, and there are coincident pairs of
331                         worlds, it is not possible to have a commander
332                         start at some worlds.)
333
334         market-fluc     The market fluctuation byte.  Affects prices at
335                         the space station.  Must be an integer between 0
336                         and 255.
337
338         fuel            Amount of fuel.  Must be between 0 and 25.5.
339
340         energy-unit     Strength of the ship's energy unit.  May be an
341                         integer between 0 (none) and 255 (scary cheat)
342                         or one of the strings `none', `standard', or
343                         `naval'.
344
345         front-laser, rear-laser, left-laser, light-laser
346                         Strength of appropriate laser.  May be an
347                         integer between 0 (none) and 255 (scary cheat)
348                         or one of the strings `none', `pulse', `beam',
349                         `mining', or `military'.
350
351         ecm, fuel-scroop, enery-bomb, escape-pod,
352         docking-computer, gal-hyperdrive
353                         Whether the ship has various bits of equipment.
354                         One of `yes', `true', or `on' for yes, or `no',
355                         `false' or `off' for no.
356
357         missiles        Number of missiles carried.  Must be an integer
358                         between 0 and 255.
359
360         hold-ITEM, station-ITEM
361                         Quantity of some item in the ship's hold, or at
362                         the station.  Must be an integer between 0 and
363                         255.  ITEM must be one of `food', `textiles',
364                         `radioactives', `slaves', `liquor-wines',
365                         `luxuries', `narcotics', `computers',
366                         `machinery', `alloys', `firearms', `furs',
367                         `minerals', `gold', `platinum', `gem-stones', or
368                         `alien-items'.
369
370         #               A special attribute which is never printed.  Its
371                         value is ignored.  This may be used to insert
372                         comments in script files.
373
374         Anything else is assumed to be a filename, and loaded as for the
375         `-load' option.
376
377
378   elite-prices [-g GALAXY] [-s SORT] [FROM [TO]]
379
380         Shows minimum, average and maximum profit (in that order, in
381         credits per unit) for the various commodities, starting at one
382         kind of world and ending at another.
383
384         By default, the commodities are listed in standard order, and
385         the profits are computed going from a poor agricultural world to
386         a rich industrial one.
387
388         You can change the worlds under consideration by typing a pair
389         of planet-specs or economy types (as printed by `elite-find').
390         Any planet-specs are obviously taken relative to GALAXY.  You
391         can also say `avg' for the average over all economy types
392         (though this takes longer to compute).
393
394         The SORT parameter may be one of `min', `max', or `avg' to sort
395         by minimum, maximum or average profit (highest at the top).
396
397         If only FROM is given, the average prices for the given world or
398         economy type are printed in the standard order (i.e., the SORT
399         parameter is ignored).
400
401
402   elite-salesman [-OPTIONS] GALAXY [START]
403
404         Solver for the Travelling Salesman Problem.  Plots a route
405         around (a connected subgraph of) GALAXY.  The START planet has
406         two related purposes:
407
408           * It identifies which subgraph to tour.  If the galaxy is split
409             into mutually unreachable subsets, it's obviously impossible
410             to visit the whole lot.
411
412           * If you specify the `-nocycle' option (see below), then START
413             is the starting place for the tour.
414
415         The following options affect the problem to be solved:
416
417         -w WEIGHT       Choose how to weight journeys.  This has the
418                         same meaning as in `elite-path'.  The default is
419                         to minimize the number of hops.
420
421         -d DIST         Distance we can travel in one hop, in
422                         lightyears.
423
424         -cycle          Find a cyclic route through the galaxy (i.e., so
425                         that when you finish, you come back to where you
426                         started).  You can use a cyclic solution to tour
427                         a galaxy from any starting point.  This is the
428                         default.
429
430         -nocycle        Find a route which begins at START, covers
431                         all the planets, and then stops.  Presumably you
432                         use a galactic hyperdrive to get to the next
433                         galaxy, or something.
434
435         The solution is displayed as a list of planet summaries.  An
436         indented line indicates a world you have to visit just to get
437         somewhere else.
438
439         The program doesn't compute an optimal solution -- doing so
440         would be very slow indeed, since the Travelling Salesman Problem
441         is NP complete.  Instead, it uses a technique called `simulated
442         annealing' to try to home in on a good solution.  There are a
443         number of options you can use to tweak this process.  The
444         default settings produce relatively good answers, but take about
445         five minutes to run.  Try playing with them, and see what sorts
446         of results you get.
447
448         -temp           The initial temperature of the system.  The
449                         temperature controls how willing the process is
450                         to accept a move which increases the journey
451                         cost -- a high temperature means that `bad'
452                         moves are more likely to be accepted.  The
453                         temperature should initially be greater than the
454                         maximum possible cost of exchanging two hops on
455                         the route.  The default is 1024, for no
456                         particularly good reason.
457
458         -cool           Cooling factor.  Each cooling cycle, the
459                         temperature is reduced by this factor.  It
460                         should be a little greater than 1.  The default
461                         is 1.001.  Smaller values (nearer 1) take longer
462                         but tend to produce better results.
463
464         -inner          Number of swapping iterations to do each cooling
465                         cycle.  The default is 10000.
466
467         -dead           The number of `dead' cycles (ones in which we
468                         never make an improving move) before we give up
469                         and accept the solution.  The default is 200,
470                         which seems to work OK.
471
472         Simulated annealing is an interesting technique which is
473         applicable to a wide variety of optimization problems.  There
474         are some decent descriptions on the 'net -- try asking Google
475         about it.
476                         
477
478 3. The graphical editor
479
480   elite-editor [GALAXY | FILE | -jameson]
481
482         Starts the RIGHT ON COMMAND-LINE Commander Editor and Map.  This
483         is a Tk program -- you'll need that installed to run it.
484
485         I'll not go into excruciating detail about how to work the
486         program.  It's fairly simple, really.
487
488         The map view lets you colour-code planets according to
489         techlevel, government or economy.  The colours ought to be as
490         follows:
491
492         Colour          Government      Economy         Techlevel
493
494         Red             Anarchy         Poor agri       1
495         Orange          Feudal          Average agri    2 or 3
496         Yellow          Multi-gov       Rich agri       4 or 5
497         Green           Dictatorship    Mainly agri     6 or 7
498         Blue            Communist       Mainly indust   8 or 9
499         Magenta         Confederacy     Poor indust     10 or 11
500         Violet          Democracy       Average indust  12 or 13
501         White           Corporate       Rich indust     14 or 15
502
503         The connectivity map shows how you can get around the galaxy
504         using hops of up to 7 light years.
505
506         Planet names are unhelpful except at small scales.  The
507         placement algorithm could do with a lot of work.
508
509         Clicking on the map with button 1 (usually the left one) sets
510         the destination world, marked with an orange cross.  Clicking
511         with button 3 (usually the right one) sets the home world,
512         marked with a red cross, and with a green hyperspace-range
513         circle around it.  (The circle doesn't actually correspond
514         exactly with hyperspace reachability, because there are rounding
515         errors in the distance computation.  ROCL correctly emulates the
516         rounding errors from the original game.)
517
518         Double-clicking opens a window showing information about a
519         planet.  Two info windows can be open at any time, one for the
520         home world and one for the destination.
521
522         The bar along the bottom of the map window shows the names of
523         the home and destination worlds, and the distance between them.
524         You can type new names (or any old planet spec) into either to
525         select different planets.  The change will take place when you
526         press return or when the input focus moves.  Pressing control-
527         return will pop up the appropriate planet info window.
528
529         The `Compute path' lets you do the same kinds of computations as
530         the elite-path tool.  It plots a route from the home to the
531         destination.  The path is shown in orange on the map.
532
533         The commander editor should be self-explanatory, but maybe a few
534         pointers might be helpful.
535
536         The entry fields for items with pop-up menus are disabled when
537         the menus show values other than `Custom', so you must first
538         choose `Custom' from the menu if you want a fancy value.
539
540         The `Show galaxy map' button opens a map which will be tied to
541         the commander window.  When you select a home world (button 3),
542         this will set the world where the commander will start.  Note
543         that the market prices (in the `Cargo' window) update
544         automatically as you move about the universe.  It is quite
545         possible to travel about entirely new universes by turning off
546         the `Standard galaxy' button and typing some hex number into the
547         `Galaxy seed' box.  All of the ROCL tools work in these custom
548         universes.  Note that your docked planet is recorded as an x, y
549         coordinate pair, so Elite can't tell which of two coincident
550         planets you're docked at (yes, there are such pairs).  ROCL
551         won't cope with this at the moment.
552
553         Lasers are a bit odd.  Bit 7 is a `rapid-fire' bit.  It doesn't
554         affect the strength of the laser, but means that there's no
555         delay between shots.  The low 7 bits control the strength, but
556         without the rapid-fire bit, powerful lasers will tend to fire
557         more slowly than weak ones.  Some comparisons in the program are
558         for exact laser power: you can't damage the Constrictor or
559         Cougar ships unless you have military (or 0x17 slow-firing)
560         lasers; and you can't fragment asteroids unless you have mining
561         or 0xb2 rapid-fire lasers.  (The 0xb2's pack a serious punch.  I
562         recommend them as an upgrade for commanders who don't wish to
563         cheat completely.)
564
565         One suggestion I've heard of, if Elite is too easy, is to start
566         at Lave (as usual), with no money, lasers, missiles, or fuel.
567         You can get your first money by ramming asteroids (easy but
568         unrewarding) or pirates (risky and tedious), and start trading
569         food and other cheap items.
570
571 $Id: README,v 1.10 2003/03/13 10:29:21 mdw Exp $
572 \f
573 Local variables:
574 mode: text
575 End: