chiark / gitweb /
Print seed -- it's useful.
[rocl] / README
CommitLineData
1304202a 1RIGHT ON COMMAND-LINE
2 Elite tools for the discerning player
3
41. 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.)
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.)
15
17b1f2a5 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
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.
30
31 In practice:
32
33 * If you can't build `pkgIndex.tcl', run `tclsh' and say
34
b6921b08 35 % pkg_mkIndex -verbose -direct -load Vec . \
36 elite.so vec.so graph.so elite.tcl
1304202a 37
b6921b08 38 to it. (Use `elite.dll' etc. if you're on Windows.) Say
1304202a 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
542. 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,
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.
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
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.
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,
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.)
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
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).
147
148
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:
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
17b1f2a5 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
1304202a 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
1ded87ba 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
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:
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
43c77c8f 374 elite-prices [-g GALAXY] [-s SORT] [FROM [TO]]
8e91ba5d 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').
43c77c8f 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).
8e91ba5d 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
43c77c8f 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
8e91ba5d 397
b6921b08 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
1304202a 4743. The graphical editor
475
ceff67f2 476 elite-editor [GALAXY | FILE | -jameson]
1304202a 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
17b1f2a5 522 press return or when the input focus moves. Pressing control-
523 return will pop up the appropriate planet info window.
1304202a 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
8e91ba5d 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
43c77c8f 567$Id: README,v 1.9 2003/03/09 23:45:02 mdw Exp $
1304202a 568\f
569Local variables:
570mode: text
571End: