--- /dev/null
+RIGHT ON COMMAND LINE
+ Developer's guide
+
+
+Package `elite'
+
+ elite-nextworld SEED
+ Given a world seed, compute and return the seed of the next
+ world in the galaxy.
+
+ elite-nextgalaxy
+ Given a galaxy seed, compute and return the seed of the next
+ galaxy.
+
+ elite-worldinfo ARR SEED
+ Given a world seed, compute information about the world and
+ return it in the array ARR. Any existing stuff in the variable
+ ARR is destroyed. Information is written to the elements of ARR
+ as follows.
+
+ x in decilightyears from galaxy left
+ y in decilightyears from galaxy top
+ government as integer: 0 .. 7 are anarchy .. corp-state
+ economy as integer: 0 .. 7 are rich-ind .. poor-agri
+ techlevel the tech level,
+ population in 100 million
+ productivity in M Cr
+ radius in km
+ seed for the sake of competeness
+ inhabitants as a string
+ name capitalized
+ description a complete sentence
+
+ The array `government' maps integers 0 to 7 to human-readable
+ strings describing the various government types; `gov' maps them
+ to short space-free tokens. Similarly, the arrays `economy' and
+ `eco' map integers to economy types.
+
+ elite-market ARR SEED [FLUC]
+ Given a world seed and an optional fluctuation (0 .. 255;
+ default is 0) compute the market prices at the world and store
+ then in the array ARR. Existing stuff in ARR is destroyed.
+ The indices of the array are product symbols; the values are
+ two-element lists containing the price and quantity available.
+ Product names are:
+
+ food textiles radioactives slaves liquor-wines
+ luxuries narcotics computers machinery alloys
+ firearms furs minerals gold platinum gem-stones
+ alien-items
+
+ The list `products' alternates these symbols with human-readable
+ product names.
+
+ elite-unpackcmdr [-force] ARR DATA
+ Unpack a commander file into an array. If `-force' is given,
+ don't complain about bad checksums or nonzero trailing bytes.
+ DATA is a string containing the file's data. ARR is an array to
+ write to; it is destroyed beforehand. Values are stashed as
+ follows:
+
+ mission mission status code
+ world-x in dly from left
+ world-y in dly from top
+ gal-seed
+ credits in tenths of a credit
+ fuel in tenths of a lightyear
+ gal-number 1 .. 8 seem sensible
+
+ front-laser bits 0 .. 6 are power; bit 7 is
+ rear-laser rapid-fire. none = 0; pulse = 15;
+ left-laser beam = 15 + rapid; mil = 23 + rapid;
+ right-laser mining = 50
+
+ cargo capacity in tonnes
+
+ market-fluc 0 .. 255; determines prices
+ hold-PRODUCT quantity of product in hold
+ station-PRODUCT quantity of product at station
+
+ ecm just true or false
+ fuel-scoop
+ energy-bomb
+ energy-unit
+ docking-computer
+ gal-hyperdrive
+ escape-pod
+
+ missiles number; 0 .. 4 are usual
+ legal-status 0 = clean; 1 .. 49 = offender;
+ 50+ = fugitive
+
+ score number
+ 0 .. 7 harmless
+ 8 .. 15 mostly harmless
+ 16 .. 31 poor
+ 32 .. 63 average
+ 64 .. 127 above average
+ 128 .. 511 competent
+ 512 .. 2559 dangerous
+ 2560 .. 6399 deadly
+ 6400+ elite
+
+ elite-packcmdr ARR
+ Given an unpacked array, as described above, construct and
+ return the packed commander file.
+
+ elite-distance X Y XX YY
+ Compute the distance between two points (X, Y) and (XX, YY),
+ expressed in decilightyears, according to the slightly strange
+ algorithm used by the game. The answer is in decilightyears.
+
+ elite-galaxylist SEED
+ Return a list of 768 elements which are the seed/x/y for each
+ world in the galaxy whose seed is SEED.
+
+ elite-adjacency ADJ LIST [DIST]
+ Given a list in the form returned by `elite-galaxylist', store
+ an adjacency map in ADJ. The DIST (by default 70) is the
+ maximum distance between two worlds for them to be considered
+ adjacent. On exit, ADJ is an array mapping seeds to seed/x/y
+ lists of adjacent worlds.
+
+ galaxy N [SEED]
+ Returns the seed of the Nth galaxy, starting counting with SEED
+ as galaxy 1. The default SEED is the standard galaxy 1.
+
+ foreach-world GAL ARR SCRIPT
+ For each world in the galaxy GAL, set ARR to information about
+ the world (see elite-worldinfo) and evaluate script.
+
+ find-world GAL PAT
+ Return a list of the worlds in galaxy GAL whose names match the
+ glob-pattern PAT.
+
+ destructure PAT LIST
+ Destructure LIST according to PAT. If PAT is a single name, set
+ the variable PAT to be LIST; otherwise if PAT is a list,
+ destructure each element of LIST according to the corresponding
+ element of PAT. If PAT is `.' then do nothing. It is not an
+ error if PAT is shorter than LIST -- trailing elements are
+ simply ignored.
+
+ write-file NAME CONTENTS [TRANS]
+ Safely write CONTENTS to the named FILE using the given
+ TRANSlation (default binary). The file is replaced atomically;
+ if there is an error then the file is not damaged.
+
+ read-file NAME [TRANS]
+ Return the contents of the named FILE according to the given
+ TRANSlation (default binary).
+
+ nearest-planet WW X Y
+ Return the seed of the `nearest' planet given in the seed/x/y
+ list WW to the point (X, Y).
+
+ worldname W
+ Return the name of the world with seed W.
+
+ shortest-path ADJ FROM TO WEIGHT
+ Computes the shortest path and shortest distance between the
+ worlds FROM and TO (both seeds). ADJ must be an adjacency table
+ (e.g., as computed by elite-adjacency) for the galaxy containing
+ both worlds. WEIGHT is a command such that WEIGHT A B returns
+ the weighting (`distance') for a hop from A to B (both seeds).
+ The return value is a list P D, where D is the total path
+ weight, and P is a list of seeds, starting with FROM and ending
+ with TO, for the route. This uses Dijkstra's shortest-path
+ algorithm. For the Floyd-Warshall all-points shortest-path
+ algorithm, see graph-shortest-path below.
+
+ weight-hops, weight-fuel, weight-safety, weight-encounters,
+ weight-trading
+ Various standard weighting functions.
+
+ parse-galaxy-spec G
+ Parses a galaxy-spec G and returns a list containing a
+ description of the galaxy and the seed. If G is not a valid
+ galaxy-spec then return an empty list.
+
+ parse-planet-spec G P
+ Parses a planet-spec P relative to a galaxy seed G, and returns
+ the planet seed or an empty string if P is invalid.
+
+ in-galaxy-p G PP
+ G is a galaxy; PP is a list of planet seeds. Return true if all
+ seeds in PP are in G. It's not a problem if the seeds in PP
+ aren't valid.
+
+ world-summary P
+ Produce a standard one-line summary of information about the
+ world P (a seed).
+
+ jameson ARR
+ Populate ARR with the standard Commander Jameson.
+
+Package `vector'
+
+ A `vector' is a fixed-size multidimensional array with integer
+ indices, whose values may be arbitrary Tcl objects.
+
+ vector LIST [INIT]
+ Construct and return a new vector whose dimensions are in LIST,
+ and whose initial contents are INIT. The vector is a command;
+ you can mess with it further using its subcommands.
+
+ VEC get INDEX ...
+ VEC lget LIST
+ VEC rget INDEX
+ Return the element at the given index. The first form reads
+ indices from successive arguments; the second collects a list of
+ arguments; the final takes a single `raw' index. Vectors use
+ row-major indexing.
+
+ VEC set INDEX ... VALUE
+ VEC lset LIST VALUE
+ VEC rset INDEX VALUE
+ Store VALUE in the given place in the vector.
+
+ VEC destroy
+ Destroy the vector VEC. Equivalent to saying rename VEC {}.
+
+ VEC bounds
+ Returns the dimension list for VEC.
+
+ VEC size
+ Returns the upper (exclusive) limit on raw indices (to rset or
+ rget).
+
+Package `graph'
+
+ graph-shortest-path VEC
+ Compute the all-points shortest-paths for VEC, which is an
+ adjacency matrix: i.e., VEC get I J is the distance from node I
+ to node J, or -1 if there is no direct route from I to J. The
+ adjacency matrix can be asymmetric -- the distance from I to J
+ need not be equal to the distance from J to I.
+
+ The return value is a pair of vectors, named LEN and PATH. The
+ length of the shortest path from I to J is then vec LEN I J; the
+ first hop is to vec PATH I J -- if we say that's node K then the
+ shortest path from I to J is I, K, and then the shortest path
+ from K to J.
+
+ graph-travelling-salesman [-OPTIONS] ADJ LIST
+ Find a short route touring all the nodes in LIST. ADJ is an
+ adjacency matrix as for graph-shortest-path, except that it must
+ be complete -- no -1 entries. (graph-shortest-path is a handy
+ way of arranging this.)
+
+ -cycle / -nocycle If -cycle (the default) then find a
+ cyclic path; if -nocycle then start at
+ the first node in LIST, and end wherever
+ is convenient.
+
+ Simulated annealing parameters:
+
+ -cool FACTOR Cooling factor. [1.001]
+ -dead COUNT Give up after COUNT cycles. [200]
+ -inner COUNT Do COUNT loops for each cooling cycle.
+ [10000]
+ -temp TEMP Start at this temperature. [unhelpful]
+
+
+$Id$
+\f
+Local variables:
+mode: text
+End:
~mdw / rocl / commitdiff