chiark / gitweb /
Fix output formatting a little.
[rocl] / README
2 Elite tools for the discerning player
41. Installation
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.)
17b1f2a5 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
1304202a 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.)
17b1f2a5 16 The runes for Debian woody are:
18 $ make INCLUDES=/usr/include/tcl8.3
19 $ ROOTLY make install prefix=/usr
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.
1304202a 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.
31 In practice:
33 * If you can't build `pkgIndex.tcl', run `tclsh' and say
b6921b08 35 % pkg_mkIndex -verbose -direct -load Vec . \
36 elite.tcl
1304202a 37
b6921b08 38 to it. (Use `elite.dll' etc. if you're on Windows.) Say
1304202a 39
40 % set tcl_pkgPath
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.
46 * Make a subdirectory in the place you chose, and copy
47 `', `elite.tcl' and `pkgIndex.tcl' into it. All
48 should now be hunky-dory.
50 * Run (say) `elite-describe lave' to check that things are set
51 up properly.
542. The command-line tools
56 A `galaxy-spec' is
58 * a number, between 1 and 8, for one of the standard eight
59 galaxies;
61 * a `galaxy seed' of 12 hex digits (a 48-bit value), for any
62 arbitrary galaxy; or
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.
68 A `planet-spec' is interpreted relative to some parent galaxy.
69 It may be
71 * a number N, for the Nth planet in the galaxy (planets are
72 numbered pseudorandomly -- this is not often a helpful
73 option);
75 * a `planet seed' of 12 hex digits (a 48-bit value), for any
76 arbitrary planet;
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;
82 * a glob pattern (a string containing `*' and `?' wildcards,
83 matching any substring or any single character,
b6921b08 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
1304202a 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.
92 elite-describe [-g GAL] PLANET ...
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.
8e91ba5d 99 elite-map [-qv] [-g GALAXY] [-d DIST] [-w WEIGHT] [-W WD,HT] [-a ASP]
100 [PLANET ...]
1304202a 101
102 Prints a map of (part of) a galaxy to the terminal.
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,
8e91ba5d 106 showing other planets within a box extending about DIST
107 lightyears around the PLANETs.
1304202a 108
8e91ba5d 109 If no PLANETs are not specified, the entire galaxy is printed.
110 This is usually unhelpful.
1304202a 111
8e91ba5d 112 The `-w' option plots a route through the listed planets,
113 highlighting the waypoints. See `elite-path' for the possible
114 weightings.
1304202a 115
8e91ba5d 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.)
125 The `-q' and `-v' options allow optional suppression of the key
126 below the map. The defaults are as follows:
128 * A galactic map shows no key.
130 * A route map (with the `-w' option) shows the waypoints
131 (named PLANETs) and the planets on the path.
133 * An area map (around named planets) shows the names of all
134 planets shown.
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'.
140 The size of the map may be controlled by the -W option -- set WD
1304202a 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).
8e91ba5d 149
b6921b08 150 elite-path [-g GALAXY] [-d DIST] [-w WEIGHT] [-a ACC] PLANET PLANET ...
1304202a 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
b6921b08 157 tech level. The `-d' option gives the ship's hyperspace range
158 in lightyears.
1304202a 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:
164 hops Minimize number of hops. This is the default.
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.
170 encounters The opposite of `safety' -- minimizes stability
171 of planets in the route. Useful if you want to
172 maximize kills.
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.
179 fuel Minimize absolute distance. For those on a
180 tight budget.
17b1f2a5 182 The `-a' option controls what total is accumulated down the
183 right hand side of the summaries:
185 none No running total down the right hand side.
187 distance Accumulate distance, in lightyears.
189 weight Accumulate the shortest-path weight function.
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.
1304202a 197
198 elite-reach [-d DIST] [GALAXY ...]
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.
207 elite-find [-g GALAXY] [EXPR]
209 Without EXPR, simply prints summary information for each planet
210 in GALAXY (default standard 1).
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:
217 name The planet name, with initial capital letter.
219 x, y X and Y coordinates, from top left, in
220 decilightyears.
222 economy From 0 (rich industrial) to 7 (poor
223 agricultural).
225 government From 0 (anarchy) to 7 (corporate state).
227 techlevel From 1 to 15.
229 radius In kilometres.
231 productivity In millions of credits.
233 population In hundreds of millions.
235 inhabitants A Tcl list of words describing the inhabitants.
237 description As a Tcl list of words.
240 elite-pairs [-g GALAXY] [-d DIST] AEXPR BEXPR
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.
247 The expressions AEXPR and BEXPR may use the same variables as
248 for elite-find. In addition, BEXPR may use
250 d The distance between planets A and B.
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.
1ded87ba 257 elite-cmdr [FILE] [-OPTION | ATTR | ATTR=VALUE | FILE] ...
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.
264 The special options are:
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.
270 -load FILE Read the commander file named FILE.
272 -save FILE Write the modified commander data to FILE.
274 -reset Reset the commander to the default `JAMESON'
275 settings.
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.
281 -read FILE Read attribute/value pairs from FILE, and modify
282 the commander accordingly.
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
d45cab7c 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.
1ded87ba 290
291 The attributes, their meanings, and the acceptable values are as
292 follows:
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.
302 score Current number of kills. Must be an integer
ea88da3d 303 between 0 and 65535, or one of the strings
1ded87ba 304 `harmless', `mostly-harmless', `poor',
305 `average', `above-average', `competent',
306 `dangerous', `deadly', or `elite'.
ea88da3d 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'.
1ded87ba 312 credits Number of credits. Must be between 0 and
313 429496729.5.
315 cargo Size of cargo bay. Must be between 4 and 255.
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.
322 gal-seed Which galaxy the commander is in. May be any
323 galaxy-spec.
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.)
334 market-fluc The market fluctuation byte. Affects prices at
335 the space station. Must be an integer between 0
336 and 255.
338 fuel Amount of fuel. Must be between 0 and 25.5.
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'.
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'.
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.
357 missiles Number of missiles carried. Must be an integer
358 between 0 and 255.
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'.
370 # A special attribute which is never printed. Its
371 value is ignored. This may be used to insert
372 comments in script files.
374 Anything else is assumed to be a filename, and loaded as for the
375 `-load' option.
43c77c8f 378 elite-prices [-g GALAXY] [-s SORT] [FROM [TO]]
8e91ba5d 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.
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.
388 You can change the worlds under consideration by typing a pair
389 of planet-specs or economy types (as printed by `elite-find').
43c77c8f 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).
8e91ba5d 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).
43c77c8f 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).
8e91ba5d 401
b6921b08 402 elite-salesman [-OPTIONS] GALAXY [START]
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:
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.
412 * If you specify the `-nocycle' option (see below), then START
413 is the starting place for the tour.
415 The following options affect the problem to be solved:
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.
421 -d DIST Distance we can travel in one hop, in
422 lightyears.
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.
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.
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.
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.
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.
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.
464 -inner Number of swapping iterations to do each cooling
465 cycle. The default is 10000.
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.
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.
74bdd262 476
478 elite-tantalus [-maxdist DIST] [-minratio RATIO] [GALAXY] ...
480 Finds pairs of worlds for which there is a large disparity
481 between the distance between them and the corresponding shortest
482 path. It reports pairs such that the distance between them is
483 less than DIST (default 8 LY -- making this large just makes the
484 program slower) and where the shortest path is more than RATIO
485 times the distance in each GALAXY specified -- by default the
486 eight standard ones.
b6921b08 487
1304202a 4893. The graphical editor
ceff67f2 491 elite-editor [GALAXY | FILE | -jameson]
1304202a 492
493 Starts the RIGHT ON COMMAND-LINE Commander Editor and Map. This
494 is a Tk program -- you'll need that installed to run it.
496 I'll not go into excruciating detail about how to work the
497 program. It's fairly simple, really.
499 The map view lets you colour-code planets according to
500 techlevel, government or economy. The colours ought to be as
501 follows:
503 Colour Government Economy Techlevel
505 Red Anarchy Poor agri 1
506 Orange Feudal Average agri 2 or 3
507 Yellow Multi-gov Rich agri 4 or 5
508 Green Dictatorship Mainly agri 6 or 7
509 Blue Communist Mainly indust 8 or 9
510 Magenta Confederacy Poor indust 10 or 11
511 Violet Democracy Average indust 12 or 13
512 White Corporate Rich indust 14 or 15
514 The connectivity map shows how you can get around the galaxy
515 using hops of up to 7 light years.
517 Planet names are unhelpful except at small scales. The
518 placement algorithm could do with a lot of work.
520 Clicking on the map with button 1 (usually the left one) sets
521 the destination world, marked with an orange cross. Clicking
522 with button 3 (usually the right one) sets the home world,
523 marked with a red cross, and with a green hyperspace-range
524 circle around it. (The circle doesn't actually correspond
525 exactly with hyperspace reachability, because there are rounding
526 errors in the distance computation. ROCL correctly emulates the
527 rounding errors from the original game.)
529 Double-clicking opens a window showing information about a
530 planet. Two info windows can be open at any time, one for the
531 home world and one for the destination.
533 The bar along the bottom of the map window shows the names of
534 the home and destination worlds, and the distance between them.
535 You can type new names (or any old planet spec) into either to
536 select different planets. The change will take place when you
17b1f2a5 537 press return or when the input focus moves. Pressing control-
538 return will pop up the appropriate planet info window.
1304202a 539
540 The `Compute path' lets you do the same kinds of computations as
541 the elite-path tool. It plots a route from the home to the
542 destination. The path is shown in orange on the map.
544 The commander editor should be self-explanatory, but maybe a few
545 pointers might be helpful.
547 The entry fields for items with pop-up menus are disabled when
548 the menus show values other than `Custom', so you must first
549 choose `Custom' from the menu if you want a fancy value.
551 The `Show galaxy map' button opens a map which will be tied to
552 the commander window. When you select a home world (button 3),
553 this will set the world where the commander will start. Note
554 that the market prices (in the `Cargo' window) update
555 automatically as you move about the universe. It is quite
556 possible to travel about entirely new universes by turning off
557 the `Standard galaxy' button and typing some hex number into the
558 `Galaxy seed' box. All of the ROCL tools work in these custom
559 universes. Note that your docked planet is recorded as an x, y
560 coordinate pair, so Elite can't tell which of two coincident
561 planets you're docked at (yes, there are such pairs). ROCL
562 won't cope with this at the moment.
564 Lasers are a bit odd. Bit 7 is a `rapid-fire' bit. It doesn't
565 affect the strength of the laser, but means that there's no
566 delay between shots. The low 7 bits control the strength, but
567 without the rapid-fire bit, powerful lasers will tend to fire
568 more slowly than weak ones. Some comparisons in the program are
569 for exact laser power: you can't damage the Constrictor or
570 Cougar ships unless you have military (or 0x17 slow-firing)
571 lasers; and you can't fragment asteroids unless you have mining
572 or 0xb2 rapid-fire lasers. (The 0xb2's pack a serious punch. I
573 recommend them as an upgrade for commanders who don't wish to
574 cheat completely.)
8e91ba5d 576 One suggestion I've heard of, if Elite is too easy, is to start
577 at Lave (as usual), with no money, lasers, missiles, or fuel.
578 You can get your first money by ramming asteroids (easy but
579 unrewarding) or pirates (risky and tedious), and start trading
580 food and other cheap items.
74bdd262 582$Id$
1304202a 583\f
584Local variables:
585mode: text