X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/rocl/blobdiff_plain/b130b8f56dda8528a9cc18e86f825f1f4283cfbc..665a500e09e1a4b20e481f1168373c111d766c75:/README diff --git a/README b/README index 1d2755a..30e32ff 100644 --- a/README +++ b/README @@ -5,14 +5,24 @@ RIGHT ON COMMAND-LINE You need a C compiler and a working Tcl/Tk installation. (The elite-editor program needs Tk; the rest of the tools don't.) - The Makefile works on my Debian GNU/Linux box, but I'm not - making any promises about anyone else's. I've successfully + The Makefile works on my Debian GNU/Linux box (potato), but I'm + not making any promises about anyone else's. I've successfully built earlier versions of everything under Cygwin, against ActiveState's Tcl 8.4, but I've forgotten the Holy Runes. I do have the `.def' file I used to build the DLL, though, for whatever that's worth. (If you want to hack the Makefile to work under Windows, I'll take a patch.) + The runes for Debian woody are: + + $ make INCLUDES=/usr/include/tcl8.3 + $ ROOTLY make install prefix=/usr + + (where ROOTLY is some command which does things with root + privileges, say `sudo', `become root' or, at a pinch, `su -c') + because the Tcl installation no longer looks in /usr/local/lib, + worse luck. + The theory is that you should edit the Makefile for your system and say `make'; then, as some suitably privileged person, say `make install' and stand well back. Everything should then be @@ -22,9 +32,10 @@ RIGHT ON COMMAND-LINE * If you can't build `pkgIndex.tcl', run `tclsh' and say - % pkg_mkIndex -verbose -direct . elite.so elite.tcl + % pkg_mkIndex -verbose -direct -load Vec . \ + elite.so vec.so graph.so elite.tcl - to it. (Use `elite.dll' if you're on Windows.) Say + to it. (Use `elite.dll' etc. if you're on Windows.) Say % set tcl_pkgPath @@ -70,8 +81,9 @@ RIGHT ON COMMAND-LINE * a glob pattern (a string containing `*' and `?' wildcards, matching any substring or any single character, - respectively), for the first planet whose name matches the - pattern; or + respectively), optionally followed by `/N' for some positive + integer N, for the Nth (default first) planet whose name + matches the pattern; or * a string `GAL:P', where GAL is a galaxy-spec and P is a planet-spec, for the planet P in galaxy GAL. @@ -84,23 +96,48 @@ RIGHT ON COMMAND-LINE GAL is not specified. - elite-map [-qv] [-g GALAXY] [-d DIST] [-w WD,HT] [-a ASP] [PLANET] + elite-map [-qv] [-g GALAXY] [-d DIST] [-w WEIGHT] [-W WD,HT] [-a ASP] + [PLANET ...] Prints a map of (part of) a galaxy to the terminal. If PLANET is specified (which it usually is), a map of the area around PLANET in GALAXY (default standard galaxy 1) is printed, - showing other planets within DIST lightyears (default 7) of - PLANET. + showing other planets within a box extending about DIST + lightyears around the PLANETs. + + If no PLANETs are not specified, the entire galaxy is printed. + This is usually unhelpful. + + The `-w' option plots a route through the listed planets, + highlighting the waypoints. See `elite-path' for the possible + weightings. + + Planets are shown as numbers or letters (or, occasionally a + sequence of letters). If there is only one PLANET, it is shown + as a `*'; otherwise, they're labelled `*0', `*1', etc. Planets + on the path are labelled `+0', `+1', ..., in the order you're + meant to visit them. (Note that if the path doubles back on + itself, the planets involved /won't/ be listed twice. Use + `elite-path' for a full guide on where to go, and `elite-map' to + visualize the route.) + + The `-q' and `-v' options allow optional suppression of the key + below the map. The defaults are as follows: + + * A galactic map shows no key. + + * A route map (with the `-w' option) shows the waypoints + (named PLANETs) and the planets on the path. - If PLANET is not specified, the entire galaxy is printed. This - is usually unhelpful. + * An area map (around named planets) shows the names of all + planets shown. - Planets are shown as numbers or letters. The home PLANET is - shown as a `*'. Below the map is printed a key describing the - planets in a strict left-to-right top-to-bottom order. + The key can be made more verbose by giving the `-v' option, or + less verbose by `-q'. Note that the options parser is currently + really shoddy, and won't let you say things like `-qqq'. - The size of the map may be controlled by the -w option -- set WD + The size of the map may be controlled by the -W option -- set WD to the maximum allowable width, and HT to the maximum allowable height (in columns and rows, respectively). The map will be scaled so as to fit. The -a option sets the aspect ratio of @@ -109,14 +146,16 @@ RIGHT ON COMMAND-LINE font). - elite-path [-g GALAXY] [-w WEIGHT] PLANET PLANET ... + + elite-path [-g GALAXY] [-d DIST] [-w WEIGHT] [-a ACC] PLANET PLANET ... Computes a route through a GALAXY (default is standard galaxy 1), starting at the first PLANET listed, via the second, via the third, etc., and ending at the last. For each planet you're meant to stop at on the way, a summary line is printed giving the planet's name, position, government type, economy type and - tech level. + tech level. The `-d' option gives the ship's hyperspace range + in lightyears. You can affect how elite-path selects its routes using the `-w' option. The default is to minimize the number of hops. Other @@ -140,6 +179,21 @@ RIGHT ON COMMAND-LINE fuel Minimize absolute distance. For those on a tight budget. + The `-a' option controls what total is accumulated down the + right hand side of the summaries: + + none No running total down the right hand side. + + distance Accumulate distance, in lightyears. + + weight Accumulate the shortest-path weight function. + + Beneath the path is printed a total for distance and weight if + these are interesting and not already displayed. The weight for + `hops' and `fuel' are simply the hop count and distance in + lightyears respectively; the other weight functions use + appropriate square-law functions. + elite-reach [-d DIST] [GALAXY ...] @@ -200,9 +254,226 @@ RIGHT ON COMMAND-LINE as the variables described above. + elite-cmdr [FILE] [-OPTION | ATTR | ATTR=VALUE | FILE] ... + + A command-line Elite commander editor and viewer. With a single + argument, reads a commander file and displays its contents as a + human readable table. The arguments may be special options, + attribute names, attribute assignments, or filenames. + + The special options are: + + -show Write the commander data to standard output as a + human-readable table. This is the default if no + other output action is requested. + + -load FILE Read the commander file named FILE. + + -save FILE Write the modified commander data to FILE. + + -reset Reset the commander to the default `JAMESON' + settings. + + -dump Write the commander data to standard output in + the form of a script which can be read back by + the `-read' option. + + -read FILE Read attribute/value pairs from FILE, and modify + the commander accordingly. + + An attribute name on its own is a request to print the current + value of that attribute. An assignment ATTR=VALUE makes ATTR + have the requested VALUE. When requesting attributes, you can + instead give a pattern containing `*' and `?' metacharacters + (matching zero or more, or exactly one character) -- all + matching attributes are printed. + + The attributes, their meanings, and the acceptable values are as + follows: + + mission The commander's current mission. (0 is no + mission; 1 is searching for the Constrictor; 2 + is killed the Constrictor; 3 is waiting for the + second mission; 4 is heading for Ceerdi; 5 is + heading for Birera; and 6 is all missions + completed.) Must be an integer between 0 and + 255. + + score Current number of kills. Must be an integer + between 0 a 65535, or one of the strings + `harmless', `mostly-harmless', `poor', + `average', `above-average', `competent', + `dangerous', `deadly', or `elite'. + + credits Number of credits. Must be between 0 and + 429496729.5. + + cargo Size of cargo bay. Must be between 4 and 255. + + gal-number Number of the current galaxy. Note that this + doesn't affect which galaxy the commander is + actually in -- set gal-seed for that. Must be + between 1 and 8. + + gal-seed Which galaxy the commander is in. May be any + galaxy-spec. + + world Which world the commander is docked at. May be + any planet-spec describing a world in the + correct galaxy. (Note that, since the commander + file actually stores the location as an x, y + pair and chooses the closest world to those + coordinates, and there are coincident pairs of + worlds, it is not possible to have a commander + start at some worlds.) + + market-fluc The market fluctuation byte. Affects prices at + the space station. Must be an integer between 0 + and 255. + + fuel Amount of fuel. Must be between 0 and 25.5. + + energy-unit Strength of the ship's energy unit. May be an + integer between 0 (none) and 255 (scary cheat) + or one of the strings `none', `standard', or + `naval'. + + front-laser, rear-laser, left-laser, light-laser + Strength of appropriate laser. May be an + integer between 0 (none) and 255 (scary cheat) + or one of the strings `none', `pulse', `beam', + `mining', or `military'. + + ecm, fuel-scroop, enery-bomb, escape-pod, + docking-computer, gal-hyperdrive + Whether the ship has various bits of equipment. + One of `yes', `true', or `on' for yes, or `no', + `false' or `off' for no. + + missiles Number of missiles carried. Must be an integer + between 0 and 255. + + hold-ITEM, station-ITEM + Quantity of some item in the ship's hold, or at + the station. Must be an integer between 0 and + 255. ITEM must be one of `food', `textiles', + `radioactives', `slaves', `liquor-wines', + `luxuries', `narcotics', `computers', + `machinery', `alloys', `firearms', `furs', + `minerals', `gold', `platinum', `gem-stones', or + `alien-items'. + + # A special attribute which is never printed. Its + value is ignored. This may be used to insert + comments in script files. + + Anything else is assumed to be a filename, and loaded as for the + `-load' option. + + + elite-prices [-g GALAXY] [-s SORT] [FROM [TO]] + + Shows minimum, average and maximum profit (in that order, in + credits per unit) for the various commodities, starting at one + kind of world and ending at another. + + By default, the commodities are listed in standard order, and + the profits are computed going from a poor agricultural world to + a rich industrial one. + + You can change the worlds under consideration by typing a pair + of planet-specs or economy types (as printed by `elite-find'). + Any planet-specs are obviously taken relative to GALAXY. You + can also say `avg' for the average over all economy types + (though this takes longer to compute). + + The SORT parameter may be one of `min', `max', or `avg' to sort + by minimum, maximum or average profit (highest at the top). + + If only FROM is given, the average prices for the given world or + economy type are printed in the standard order (i.e., the SORT + parameter is ignored). + + + elite-salesman [-OPTIONS] GALAXY [START] + + Solver for the Travelling Salesman Problem. Plots a route + around (a connected subgraph of) GALAXY. The START planet has + two related purposes: + + * It identifies which subgraph to tour. If the galaxy is split + into mutually unreachable subsets, it's obviously impossible + to visit the whole lot. + + * If you specify the `-nocycle' option (see below), then START + is the starting place for the tour. + + The following options affect the problem to be solved: + + -w WEIGHT Choose how to weight journeys. This has the + same meaning as in `elite-path'. The default is + to minimize the number of hops. + + -d DIST Distance we can travel in one hop, in + lightyears. + + -cycle Find a cyclic route through the galaxy (i.e., so + that when you finish, you come back to where you + started). You can use a cyclic solution to tour + a galaxy from any starting point. This is the + default. + + -nocycle Find a route which begins at START, covers + all the planets, and then stops. Presumably you + use a galactic hyperdrive to get to the next + galaxy, or something. + + The solution is displayed as a list of planet summaries. An + indented line indicates a world you have to visit just to get + somewhere else. + + The program doesn't compute an optimal solution -- doing so + would be very slow indeed, since the Travelling Salesman Problem + is NP complete. Instead, it uses a technique called `simulated + annealing' to try to home in on a good solution. There are a + number of options you can use to tweak this process. The + default settings produce relatively good answers, but take about + five minutes to run. Try playing with them, and see what sorts + of results you get. + + -temp The initial temperature of the system. The + temperature controls how willing the process is + to accept a move which increases the journey + cost -- a high temperature means that `bad' + moves are more likely to be accepted. The + temperature should initially be greater than the + maximum possible cost of exchanging two hops on + the route. The default is 1024, for no + particularly good reason. + + -cool Cooling factor. Each cooling cycle, the + temperature is reduced by this factor. It + should be a little greater than 1. The default + is 1.001. Smaller values (nearer 1) take longer + but tend to produce better results. + + -inner Number of swapping iterations to do each cooling + cycle. The default is 10000. + + -dead The number of `dead' cycles (ones in which we + never make an improving move) before we give up + and accept the solution. The default is 200, + which seems to work OK. + + Simulated annealing is an interesting technique which is + applicable to a wide variety of optimization problems. There + are some decent descriptions on the 'net -- try asking Google + about it. + + 3. The graphical editor - elite-editor [GALAXY | FILE] + elite-editor [GALAXY | FILE | -jameson] Starts the RIGHT ON COMMAND-LINE Commander Editor and Map. This is a Tk program -- you'll need that installed to run it. @@ -248,7 +519,8 @@ RIGHT ON COMMAND-LINE the home and destination worlds, and the distance between them. You can type new names (or any old planet spec) into either to select different planets. The change will take place when you - press return or when the input focus moves. + press return or when the input focus moves. Pressing control- + return will pop up the appropriate planet info window. The `Compute path' lets you do the same kinds of computations as the elite-path tool. It plots a route from the home to the @@ -286,7 +558,13 @@ RIGHT ON COMMAND-LINE recommend them as an upgrade for commanders who don't wish to cheat completely.) -$Id: README,v 1.2 2003/02/25 00:25:38 mdw Exp $ + One suggestion I've heard of, if Elite is too easy, is to start + at Lave (as usual), with no money, lasers, missiles, or fuel. + You can get your first money by ramming asteroids (easy but + unrewarding) or pirates (risky and tedious), and start trading + food and other cheap items. + +$Id: README,v 1.9 2003/03/09 23:45:02 mdw Exp $ Local variables: mode: text