Lots of new files.

[rocl] / README

RIGHT ON COMMAND-LINE
  Elite tools for the discerning player

1. Installation

        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 (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
        installed.

        In practice:

          * If you can't build `pkgIndex.tcl', run `tclsh' and say

              % pkg_mkIndex -verbose -direct -load Vec . \
                elite.so vec.so graph.so elite.tcl

            to it.  (Use `elite.dll' etc. if you're on Windows.)  Say

              % set tcl_pkgPath

            to see a list of suitable places for putting the kit.  Pick
            one.  The directory `/usr/local/lib' appears in my
            installation, so that's what I use.

          * Make a subdirectory in the place you chose, and copy
            `elite.so', `elite.tcl' and `pkgIndex.tcl' into it.  All
            should now be hunky-dory.

          * Run (say) `elite-describe lave' to check that things are set
            up properly.


2. The command-line tools

        A `galaxy-spec' is

          * a number, between 1 and 8, for one of the standard eight
            galaxies; 

          * a `galaxy seed' of 12 hex digits (a 48-bit value), for any
            arbitrary galaxy; or

          * a string `SEED:N' where SEED is a galaxy seed and N is a
            number between 1 and 8, for the Nth galaxy in some custom
            universe.

        A `planet-spec' is interpreted relative to some parent galaxy.
        It may be

          * a number N, for the Nth planet in the galaxy (planets are
            numbered pseudorandomly -- this is not often a helpful
            option);

          * a `planet seed' of 12 hex digits (a 48-bit value), for any
            arbitrary planet;

          * a pair of numbers `X,Y', for the planet nearest the point X
            decilightyears rightwards and T decilightyears down from the
            top left of the galaxy;

          * a glob pattern (a string containing `*' and `?' wildcards,
            matching any substring or any single character,
            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.


  elite-describe [-g GAL] PLANET ...

        For each PLANET, print the planet data for that PLANET.  The
        PLANETs are interpreted relative to GAL, or standard galaxy 1 if
        GAL is not specified.


  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 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.

          * An area map (around named planets) shows the names of all
            planets shown.

        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
        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
        your characters, height to width (the default is about 2, and
        seems right for viewing in an xterm with the standard fixed
        font).



  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.  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
        possibilities are:

        hops            Minimize number of hops.  This is the default.

        safety          Maximize stability of the planets in the route,
                        to attempt to improve safety.  Useful during the
                        early stages of the game.

        encounters      The opposite of `safety' -- minimizes stability
                        of planets in the route.  Useful if you want to
                        maximize kills.

        trading         Maximize the difference in economy type between
                        successive planets in the route.  This should
                        give you an opportunity to make a good profit as
                        you go.

        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 ...]

        For each GALAXY (default is the 8 standard ones), print summary
        information for each planet, with blank lines separating
        disconnected groups of planets, i.e., groups where a ship
        capable of travelling DIST lightyears (default 7) can't get from
        one to the other.


  elite-find [-g GALAXY] [EXPR]

        Without EXPR, simply prints summary information for each planet
        in GALAXY (default standard 1).

        If EXPR is specified, it must be a Tcl expression (as for the
        `expr' command).  Information is printed for each planet for
        which EXPR returns nonzero.  The EXPR may use the following
        variables:

        name            The planet name, with initial capital letter.

        x, y            X and Y coordinates, from top left, in
                        decilightyears.

        economy         From 0 (rich industrial) to 7 (poor
                        agricultural).

        government      From 0 (anarchy) to 7 (corporate state).

        techlevel       From 1 to 15.

        radius          In kilometres.

        productivity    In millions of credits.

        population      In hundreds of millions.

        inhabitants     A Tcl list of words describing the inhabitants.

        description     As a Tcl list of words.


  elite-pairs [-g GALAXY] [-d DIST] AEXPR BEXPR

        Prints the names of pairs of planets A and B in GALAXY (default
        standard 1), no further than DIST (default 7) lightyears apart,
        such that AEXPR returns nonzero for planet A and BEXPR returns
        nonzero for planet B.

        The expressions AEXPR and BEXPR may use the same variables as
        for elite-find.  In addition, BEXPR may use

        d               The distance between planets A and B.

        a               An array containing the information about planet
                        A.  The indices have the same names and meanings
                        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.

        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.

        The SORT parameter may be one of `min', `max', or `avg' to sort
        by minimum, maximum or average profit (highest at the top).


  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 | -jameson]

        Starts the RIGHT ON COMMAND-LINE Commander Editor and Map.  This
        is a Tk program -- you'll need that installed to run it.

        I'll not go into excruciating detail about how to work the
        program.  It's fairly simple, really.

        The map view lets you colour-code planets according to
        techlevel, government or economy.  The colours ought to be as
        follows:

        Colour          Government      Economy         Techlevel

        Red             Anarchy         Poor agri       1
        Orange          Feudal          Average agri    2 or 3
        Yellow          Multi-gov       Rich agri       4 or 5
        Green           Dictatorship    Mainly agri     6 or 7
        Blue            Communist       Mainly indust   8 or 9
        Magenta         Confederacy     Poor indust     10 or 11
        Violet          Democracy       Average indust  12 or 13
        White           Corporate       Rich indust     14 or 15

        The connectivity map shows how you can get around the galaxy
        using hops of up to 7 light years.

        Planet names are unhelpful except at small scales.  The
        placement algorithm could do with a lot of work.

        Clicking on the map with button 1 (usually the left one) sets
        the destination world, marked with an orange cross.  Clicking
        with button 3 (usually the right one) sets the home world,
        marked with a red cross, and with a green hyperspace-range
        circle around it.  (The circle doesn't actually correspond
        exactly with hyperspace reachability, because there are rounding
        errors in the distance computation.  ROCL correctly emulates the
        rounding errors from the original game.)

        Double-clicking opens a window showing information about a
        planet.  Two info windows can be open at any time, one for the
        home world and one for the destination.

        The bar along the bottom of the map window shows the names of
        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.  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
        destination.  The path is shown in orange on the map.

        The commander editor should be self-explanatory, but maybe a few
        pointers might be helpful.

        The entry fields for items with pop-up menus are disabled when
        the menus show values other than `Custom', so you must first
        choose `Custom' from the menu if you want a fancy value.

        The `Show galaxy map' button opens a map which will be tied to
        the commander window.  When you select a home world (button 3),
        this will set the world where the commander will start.  Note
        that the market prices (in the `Cargo' window) update
        automatically as you move about the universe.  It is quite
        possible to travel about entirely new universes by turning off
        the `Standard galaxy' button and typing some hex number into the
        `Galaxy seed' box.  All of the ROCL tools work in these custom
        universes.  Note that your docked planet is recorded as an x, y
        coordinate pair, so Elite can't tell which of two coincident
        planets you're docked at (yes, there are such pairs).  ROCL
        won't cope with this at the moment.

        Lasers are a bit odd.  Bit 7 is a `rapid-fire' bit.  It doesn't
        affect the strength of the laser, but means that there's no
        delay between shots.  The low 7 bits control the strength, but
        without the rapid-fire bit, powerful lasers will tend to fire
        more slowly than weak ones.  Some comparisons in the program are
        for exact laser power: you can't damage the Constrictor or
        Cougar ships unless you have military (or 0x17 slow-firing)
        lasers; and you can't fragment asteroids unless you have mining
        or 0xb2 rapid-fire lasers.  (The 0xb2's pack a serious punch.  I
        recommend them as an upgrade for commanders who don't wish to
        cheat completely.)

        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.7 2003/03/07 00:47:13 mdw Exp $
\f
Local variables:
mode: text
End: