chiark / gitweb /
Fix nonexistent planet error. Make staying put cost nothing.
[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 a 65535, or one of the strings
304                         `harmless', `mostly-harmless', `poor',
305                         `average', `above-average', `competent',
306                         `dangerous', `deadly', or `elite'.
307
308         credits         Number of credits.  Must be between 0 and
309                         429496729.5.
310
311         cargo           Size of cargo bay.  Must be between 4 and 255.
312
313         gal-number      Number of the current galaxy.  Note that this
314                         doesn't affect which galaxy the commander is
315                         actually in -- set gal-seed for that.  Must be
316                         between 1 and 8.
317
318         gal-seed        Which galaxy the commander is in.  May be any
319                         galaxy-spec.
320
321         world           Which world the commander is docked at.  May be
322                         any planet-spec describing a world in the
323                         correct galaxy.  (Note that, since the commander
324                         file actually stores the location as an x, y
325                         pair and chooses the closest world to those
326                         coordinates, and there are coincident pairs of
327                         worlds, it is not possible to have a commander
328                         start at some worlds.)
329
330         market-fluc     The market fluctuation byte.  Affects prices at
331                         the space station.  Must be an integer between 0
332                         and 255.
333
334         fuel            Amount of fuel.  Must be between 0 and 25.5.
335
336         energy-unit     Strength of the ship's energy unit.  May be an
337                         integer between 0 (none) and 255 (scary cheat)
338                         or one of the strings `none', `standard', or
339                         `naval'.
340
341         front-laser, rear-laser, left-laser, light-laser
342                         Strength of appropriate laser.  May be an
343                         integer between 0 (none) and 255 (scary cheat)
344                         or one of the strings `none', `pulse', `beam',
345                         `mining', or `military'.
346
347         ecm, fuel-scroop, enery-bomb, escape-pod,
348         docking-computer, gal-hyperdrive
349                         Whether the ship has various bits of equipment.
350                         One of `yes', `true', or `on' for yes, or `no',
351                         `false' or `off' for no.
352
353         missiles        Number of missiles carried.  Must be an integer
354                         between 0 and 255.
355
356         hold-ITEM, station-ITEM
357                         Quantity of some item in the ship's hold, or at
358                         the station.  Must be an integer between 0 and
359                         255.  ITEM must be one of `food', `textiles',
360                         `radioactives', `slaves', `liquor-wines',
361                         `luxuries', `narcotics', `computers',
362                         `machinery', `alloys', `firearms', `furs',
363                         `minerals', `gold', `platinum', `gem-stones', or
364                         `alien-items'.
365
366         #               A special attribute which is never printed.  Its
367                         value is ignored.  This may be used to insert
368                         comments in script files.
369
370         Anything else is assumed to be a filename, and loaded as for the
371         `-load' option.
372
373
374   elite-prices [-g GALAXY] [-s SORT] [FROM [TO]]
375
376         Shows minimum, average and maximum profit (in that order, in
377         credits per unit) for the various commodities, starting at one
378         kind of world and ending at another.
379
380         By default, the commodities are listed in standard order, and
381         the profits are computed going from a poor agricultural world to
382         a rich industrial one.
383
384         You can change the worlds under consideration by typing a pair
385         of planet-specs or economy types (as printed by `elite-find').
386         Any planet-specs are obviously taken relative to GALAXY.  You
387         can also say `avg' for the average over all economy types
388         (though this takes longer to compute).
389
390         The SORT parameter may be one of `min', `max', or `avg' to sort
391         by minimum, maximum or average profit (highest at the top).
392
393         If only FROM is given, the average prices for the given world or
394         economy type are printed in the standard order (i.e., the SORT
395         parameter is ignored).
396
397
398   elite-salesman [-OPTIONS] GALAXY [START]
399
400         Solver for the Travelling Salesman Problem.  Plots a route
401         around (a connected subgraph of) GALAXY.  The START planet has
402         two related purposes:
403
404           * It identifies which subgraph to tour.  If the galaxy is split
405             into mutually unreachable subsets, it's obviously impossible
406             to visit the whole lot.
407
408           * If you specify the `-nocycle' option (see below), then START
409             is the starting place for the tour.
410
411         The following options affect the problem to be solved:
412
413         -w WEIGHT       Choose how to weight journeys.  This has the
414                         same meaning as in `elite-path'.  The default is
415                         to minimize the number of hops.
416
417         -d DIST         Distance we can travel in one hop, in
418                         lightyears.
419
420         -cycle          Find a cyclic route through the galaxy (i.e., so
421                         that when you finish, you come back to where you
422                         started).  You can use a cyclic solution to tour
423                         a galaxy from any starting point.  This is the
424                         default.
425
426         -nocycle        Find a route which begins at START, covers
427                         all the planets, and then stops.  Presumably you
428                         use a galactic hyperdrive to get to the next
429                         galaxy, or something.
430
431         The solution is displayed as a list of planet summaries.  An
432         indented line indicates a world you have to visit just to get
433         somewhere else.
434
435         The program doesn't compute an optimal solution -- doing so
436         would be very slow indeed, since the Travelling Salesman Problem
437         is NP complete.  Instead, it uses a technique called `simulated
438         annealing' to try to home in on a good solution.  There are a
439         number of options you can use to tweak this process.  The
440         default settings produce relatively good answers, but take about
441         five minutes to run.  Try playing with them, and see what sorts
442         of results you get.
443
444         -temp           The initial temperature of the system.  The
445                         temperature controls how willing the process is
446                         to accept a move which increases the journey
447                         cost -- a high temperature means that `bad'
448                         moves are more likely to be accepted.  The
449                         temperature should initially be greater than the
450                         maximum possible cost of exchanging two hops on
451                         the route.  The default is 1024, for no
452                         particularly good reason.
453
454         -cool           Cooling factor.  Each cooling cycle, the
455                         temperature is reduced by this factor.  It
456                         should be a little greater than 1.  The default
457                         is 1.001.  Smaller values (nearer 1) take longer
458                         but tend to produce better results.
459
460         -inner          Number of swapping iterations to do each cooling
461                         cycle.  The default is 10000.
462
463         -dead           The number of `dead' cycles (ones in which we
464                         never make an improving move) before we give up
465                         and accept the solution.  The default is 200,
466                         which seems to work OK.
467
468         Simulated annealing is an interesting technique which is
469         applicable to a wide variety of optimization problems.  There
470         are some decent descriptions on the 'net -- try asking Google
471         about it.
472                         
473
474 3. The graphical editor
475
476   elite-editor [GALAXY | FILE | -jameson]
477
478         Starts the RIGHT ON COMMAND-LINE Commander Editor and Map.  This
479         is a Tk program -- you'll need that installed to run it.
480
481         I'll not go into excruciating detail about how to work the
482         program.  It's fairly simple, really.
483
484         The map view lets you colour-code planets according to
485         techlevel, government or economy.  The colours ought to be as
486         follows:
487
488         Colour          Government      Economy         Techlevel
489
490         Red             Anarchy         Poor agri       1
491         Orange          Feudal          Average agri    2 or 3
492         Yellow          Multi-gov       Rich agri       4 or 5
493         Green           Dictatorship    Mainly agri     6 or 7
494         Blue            Communist       Mainly indust   8 or 9
495         Magenta         Confederacy     Poor indust     10 or 11
496         Violet          Democracy       Average indust  12 or 13
497         White           Corporate       Rich indust     14 or 15
498
499         The connectivity map shows how you can get around the galaxy
500         using hops of up to 7 light years.
501
502         Planet names are unhelpful except at small scales.  The
503         placement algorithm could do with a lot of work.
504
505         Clicking on the map with button 1 (usually the left one) sets
506         the destination world, marked with an orange cross.  Clicking
507         with button 3 (usually the right one) sets the home world,
508         marked with a red cross, and with a green hyperspace-range
509         circle around it.  (The circle doesn't actually correspond
510         exactly with hyperspace reachability, because there are rounding
511         errors in the distance computation.  ROCL correctly emulates the
512         rounding errors from the original game.)
513
514         Double-clicking opens a window showing information about a
515         planet.  Two info windows can be open at any time, one for the
516         home world and one for the destination.
517
518         The bar along the bottom of the map window shows the names of
519         the home and destination worlds, and the distance between them.
520         You can type new names (or any old planet spec) into either to
521         select different planets.  The change will take place when you
522         press return or when the input focus moves.  Pressing control-
523         return will pop up the appropriate planet info window.
524
525         The `Compute path' lets you do the same kinds of computations as
526         the elite-path tool.  It plots a route from the home to the
527         destination.  The path is shown in orange on the map.
528
529         The commander editor should be self-explanatory, but maybe a few
530         pointers might be helpful.
531
532         The entry fields for items with pop-up menus are disabled when
533         the menus show values other than `Custom', so you must first
534         choose `Custom' from the menu if you want a fancy value.
535
536         The `Show galaxy map' button opens a map which will be tied to
537         the commander window.  When you select a home world (button 3),
538         this will set the world where the commander will start.  Note
539         that the market prices (in the `Cargo' window) update
540         automatically as you move about the universe.  It is quite
541         possible to travel about entirely new universes by turning off
542         the `Standard galaxy' button and typing some hex number into the
543         `Galaxy seed' box.  All of the ROCL tools work in these custom
544         universes.  Note that your docked planet is recorded as an x, y
545         coordinate pair, so Elite can't tell which of two coincident
546         planets you're docked at (yes, there are such pairs).  ROCL
547         won't cope with this at the moment.
548
549         Lasers are a bit odd.  Bit 7 is a `rapid-fire' bit.  It doesn't
550         affect the strength of the laser, but means that there's no
551         delay between shots.  The low 7 bits control the strength, but
552         without the rapid-fire bit, powerful lasers will tend to fire
553         more slowly than weak ones.  Some comparisons in the program are
554         for exact laser power: you can't damage the Constrictor or
555         Cougar ships unless you have military (or 0x17 slow-firing)
556         lasers; and you can't fragment asteroids unless you have mining
557         or 0xb2 rapid-fire lasers.  (The 0xb2's pack a serious punch.  I
558         recommend them as an upgrade for commanders who don't wish to
559         cheat completely.)
560
561         One suggestion I've heard of, if Elite is too easy, is to start
562         at Lave (as usual), with no money, lasers, missiles, or fuel.
563         You can get your first money by ramming asteroids (easy but
564         unrewarding) or pirates (risky and tedious), and start trading
565         food and other cheap items.
566
567 $Id: README,v 1.9 2003/03/09 23:45:02 mdw Exp $
568 \f
569 Local variables:
570 mode: text
571 End: