X-Git-Url: https://git.distorted.org.uk/~mdw/rocl/blobdiff_plain/c53e2dd3a5c32cb945a0a68dd96161badb4d14eb..74bdd262742db2f0b2b97375ece36f2962bfeb52:/DEVGUIDE diff --git a/DEVGUIDE b/DEVGUIDE new file mode 100644 index 0000000..6561dc7 --- /dev/null +++ b/DEVGUIDE @@ -0,0 +1,269 @@ +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$ + +Local variables: +mode: text +End: