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 [IND [SPC]] Produce a standard one-line summary of information about the world P (a seed). IND is the number of spaces to insert before the world name, and SPC is the number of additional spaces to insert afterwards; both default to 0 if not supplied. world-brief P Produce a very short summary about the world P, showing its name, tech-level, and cryptic abbreviations for economic and government status. 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$ Local variables: mode: text End: