| 1 | RIGHT ON COMMAND LINE |
| 2 | Developer's guide |
| 3 | |
| 4 | |
| 5 | Package `elite' |
| 6 | |
| 7 | elite-nextworld SEED |
| 8 | Given a world seed, compute and return the seed of the next |
| 9 | world in the galaxy. |
| 10 | |
| 11 | elite-nextgalaxy |
| 12 | Given a galaxy seed, compute and return the seed of the next |
| 13 | galaxy. |
| 14 | |
| 15 | elite-worldinfo ARR SEED |
| 16 | Given a world seed, compute information about the world and |
| 17 | return it in the array ARR. Any existing stuff in the variable |
| 18 | ARR is destroyed. Information is written to the elements of ARR |
| 19 | as follows. |
| 20 | |
| 21 | x in decilightyears from galaxy left |
| 22 | y in decilightyears from galaxy top |
| 23 | government as integer: 0 .. 7 are anarchy .. corp-state |
| 24 | economy as integer: 0 .. 7 are rich-ind .. poor-agri |
| 25 | techlevel the tech level |
| 26 | population in 100 million |
| 27 | productivity in M Cr |
| 28 | radius in km |
| 29 | seed for the sake of competeness |
| 30 | inhabitants as a string |
| 31 | name capitalized |
| 32 | description a complete sentence |
| 33 | |
| 34 | The array `government' maps integers 0 to 7 to human-readable |
| 35 | strings describing the various government types; `gov' maps them |
| 36 | to short space-free tokens. Similarly, the arrays `economy' and |
| 37 | `eco' map integers to economy types. |
| 38 | |
| 39 | elite-market ARR SEED [FLUC] |
| 40 | Given a world seed and an optional fluctuation (0 .. 255; |
| 41 | default is 0) compute the market prices at the world and store |
| 42 | then in the array ARR. Existing stuff in ARR is destroyed. |
| 43 | The indices of the array are product symbols; the values are |
| 44 | two-element lists containing the price and quantity available. |
| 45 | Product names are: |
| 46 | |
| 47 | food textiles radioactives slaves liquor-wines |
| 48 | luxuries narcotics computers machinery alloys |
| 49 | firearms furs minerals gold platinum gem-stones |
| 50 | alien-items |
| 51 | |
| 52 | The list `products' alternates these symbols with human-readable |
| 53 | product names. |
| 54 | |
| 55 | elite-unpackcmdr [-force] ARR DATA |
| 56 | Unpack a commander file into an array. If `-force' is given, |
| 57 | don't complain about bad checksums or nonzero trailing bytes. |
| 58 | DATA is a string containing the file's data. ARR is an array to |
| 59 | write to; it is destroyed beforehand. Values are stashed as |
| 60 | follows: |
| 61 | |
| 62 | mission mission status code |
| 63 | world-x in dly from left |
| 64 | world-y in dly from top |
| 65 | gal-seed |
| 66 | credits in tenths of a credit |
| 67 | fuel in tenths of a lightyear |
| 68 | gal-number 1 .. 8 seem sensible |
| 69 | |
| 70 | front-laser bits 0 .. 6 are power; bit 7 is |
| 71 | rear-laser rapid-fire. none = 0; pulse = 15; |
| 72 | left-laser beam = 15 + rapid; mil = 23 + rapid; |
| 73 | right-laser mining = 50 |
| 74 | |
| 75 | cargo capacity in tonnes |
| 76 | |
| 77 | market-fluc 0 .. 255; determines prices |
| 78 | hold-PRODUCT quantity of product in hold |
| 79 | station-PRODUCT quantity of product at station |
| 80 | |
| 81 | ecm just true or false |
| 82 | fuel-scoop |
| 83 | energy-bomb |
| 84 | energy-unit |
| 85 | docking-computer |
| 86 | gal-hyperdrive |
| 87 | escape-pod |
| 88 | |
| 89 | missiles number; 0 .. 4 are usual |
| 90 | legal-status 0 = clean; 1 .. 49 = offender; |
| 91 | 50+ = fugitive |
| 92 | |
| 93 | score number |
| 94 | 0 .. 7 harmless |
| 95 | 8 .. 15 mostly harmless |
| 96 | 16 .. 31 poor |
| 97 | 32 .. 63 average |
| 98 | 64 .. 127 above average |
| 99 | 128 .. 511 competent |
| 100 | 512 .. 2559 dangerous |
| 101 | 2560 .. 6399 deadly |
| 102 | 6400+ elite |
| 103 | |
| 104 | elite-packcmdr ARR |
| 105 | Given an unpacked array, as described above, construct and |
| 106 | return the packed commander file. |
| 107 | |
| 108 | elite-distance X Y XX YY |
| 109 | Compute the distance between two points (X, Y) and (XX, YY), |
| 110 | expressed in decilightyears, according to the slightly strange |
| 111 | algorithm used by the game. The answer is in decilightyears. |
| 112 | |
| 113 | elite-galaxylist SEED |
| 114 | Return a list of 768 elements which are the seed/x/y for each |
| 115 | world in the galaxy whose seed is SEED. |
| 116 | |
| 117 | elite-adjacency ADJ LIST [DIST] |
| 118 | Given a list in the form returned by `elite-galaxylist', store |
| 119 | an adjacency map in ADJ. The DIST (by default 70) is the |
| 120 | maximum distance between two worlds for them to be considered |
| 121 | adjacent. On exit, ADJ is an array mapping seeds to seed/x/y |
| 122 | lists of adjacent worlds. |
| 123 | |
| 124 | galaxy N [SEED] |
| 125 | Returns the seed of the Nth galaxy, starting counting with SEED |
| 126 | as galaxy 1. The default SEED is the standard galaxy 1. |
| 127 | |
| 128 | foreach-world GAL ARR SCRIPT |
| 129 | For each world in the galaxy GAL, set ARR to information about |
| 130 | the world (see elite-worldinfo) and evaluate script. |
| 131 | |
| 132 | find-world GAL PAT |
| 133 | Return a list of the worlds in galaxy GAL whose names match the |
| 134 | glob-pattern PAT. |
| 135 | |
| 136 | destructure PAT LIST |
| 137 | Destructure LIST according to PAT. If PAT is a single name, set |
| 138 | the variable PAT to be LIST; otherwise if PAT is a list, |
| 139 | destructure each element of LIST according to the corresponding |
| 140 | element of PAT. If PAT is `.' then do nothing. It is not an |
| 141 | error if PAT is shorter than LIST -- trailing elements are |
| 142 | simply ignored. |
| 143 | |
| 144 | write-file NAME CONTENTS [TRANS] |
| 145 | Safely write CONTENTS to the named FILE using the given |
| 146 | TRANSlation (default binary). The file is replaced atomically; |
| 147 | if there is an error then the file is not damaged. |
| 148 | |
| 149 | read-file NAME [TRANS] |
| 150 | Return the contents of the named FILE according to the given |
| 151 | TRANSlation (default binary). |
| 152 | |
| 153 | nearest-planet WW X Y |
| 154 | Return the seed of the `nearest' planet given in the seed/x/y |
| 155 | list WW to the point (X, Y). |
| 156 | |
| 157 | worldname W |
| 158 | Return the name of the world with seed W. |
| 159 | |
| 160 | shortest-path ADJ FROM TO WEIGHT |
| 161 | Computes the shortest path and shortest distance between the |
| 162 | worlds FROM and TO (both seeds). ADJ must be an adjacency table |
| 163 | (e.g., as computed by elite-adjacency) for the galaxy containing |
| 164 | both worlds. WEIGHT is a command such that WEIGHT A B returns |
| 165 | the weighting (`distance') for a hop from A to B (both seeds). |
| 166 | The return value is a list P D, where D is the total path |
| 167 | weight, and P is a list of seeds, starting with FROM and ending |
| 168 | with TO, for the route. This uses Dijkstra's shortest-path |
| 169 | algorithm. For the Floyd-Warshall all-points shortest-path |
| 170 | algorithm, see graph-shortest-path below. |
| 171 | |
| 172 | weight-hops, weight-fuel, weight-safety, weight-encounters, |
| 173 | weight-trading |
| 174 | Various standard weighting functions. |
| 175 | |
| 176 | parse-galaxy-spec G |
| 177 | Parses a galaxy-spec G and returns a list containing a |
| 178 | description of the galaxy and the seed. If G is not a valid |
| 179 | galaxy-spec then return an empty list. |
| 180 | |
| 181 | parse-planet-spec G P |
| 182 | Parses a planet-spec P relative to a galaxy seed G, and returns |
| 183 | the planet seed or an empty string if P is invalid. |
| 184 | |
| 185 | in-galaxy-p G PP |
| 186 | G is a galaxy; PP is a list of planet seeds. Return true if all |
| 187 | seeds in PP are in G. It's not a problem if the seeds in PP |
| 188 | aren't valid. |
| 189 | |
| 190 | world-summary P [IND [SPC]] |
| 191 | Produce a standard one-line summary of information about the |
| 192 | world P (a seed). IND is the number of spaces to insert before |
| 193 | the world name, and SPC is the number of additional spaces to |
| 194 | insert afterwards; both default to 0 if not supplied. |
| 195 | |
| 196 | world-brief P |
| 197 | Produce a very short summary about the world P, showing its |
| 198 | name, tech-level, and cryptic abbreviations for economic and |
| 199 | government status. |
| 200 | |
| 201 | jameson ARR |
| 202 | Populate ARR with the standard Commander Jameson. |
| 203 | |
| 204 | Package `vector' |
| 205 | |
| 206 | A `vector' is a fixed-size multidimensional array with integer |
| 207 | indices, whose values may be arbitrary Tcl objects. |
| 208 | |
| 209 | vector LIST [INIT] |
| 210 | Construct and return a new vector whose dimensions are in LIST, |
| 211 | and whose initial contents are INIT. The vector is a command; |
| 212 | you can mess with it further using its subcommands. |
| 213 | |
| 214 | VEC get INDEX ... |
| 215 | VEC lget LIST |
| 216 | VEC rget INDEX |
| 217 | Return the element at the given index. The first form reads |
| 218 | indices from successive arguments; the second collects a list of |
| 219 | arguments; the final takes a single `raw' index. Vectors use |
| 220 | row-major indexing. |
| 221 | |
| 222 | VEC set INDEX ... VALUE |
| 223 | VEC lset LIST VALUE |
| 224 | VEC rset INDEX VALUE |
| 225 | Store VALUE in the given place in the vector. |
| 226 | |
| 227 | VEC destroy |
| 228 | Destroy the vector VEC. Equivalent to saying rename VEC {}. |
| 229 | |
| 230 | VEC bounds |
| 231 | Returns the dimension list for VEC. |
| 232 | |
| 233 | VEC size |
| 234 | Returns the upper (exclusive) limit on raw indices (to rset or |
| 235 | rget). |
| 236 | |
| 237 | Package `graph' |
| 238 | |
| 239 | graph-shortest-path VEC |
| 240 | Compute the all-points shortest-paths for VEC, which is an |
| 241 | adjacency matrix: i.e., VEC get I J is the distance from node I |
| 242 | to node J, or -1 if there is no direct route from I to J. The |
| 243 | adjacency matrix can be asymmetric -- the distance from I to J |
| 244 | need not be equal to the distance from J to I. |
| 245 | |
| 246 | The return value is a pair of vectors, named LEN and PATH. The |
| 247 | length of the shortest path from I to J is then vec LEN I J; the |
| 248 | first hop is to vec PATH I J -- if we say that's node K then the |
| 249 | shortest path from I to J is I, K, and then the shortest path |
| 250 | from K to J. |
| 251 | |
| 252 | graph-travelling-salesman [-OPTIONS] ADJ LIST |
| 253 | Find a short route touring all the nodes in LIST. ADJ is an |
| 254 | adjacency matrix as for graph-shortest-path, except that it must |
| 255 | be complete -- no -1 entries. (graph-shortest-path is a handy |
| 256 | way of arranging this.) |
| 257 | |
| 258 | -cycle / -nocycle If -cycle (the default) then find a |
| 259 | cyclic path; if -nocycle then start at |
| 260 | the first node in LIST, and end wherever |
| 261 | is convenient. |
| 262 | |
| 263 | Simulated annealing parameters: |
| 264 | |
| 265 | -cool FACTOR Cooling factor. [1.001] |
| 266 | -dead COUNT Give up after COUNT cycles. [200] |
| 267 | -inner COUNT Do COUNT loops for each cooling cycle. |
| 268 | [10000] |
| 269 | -temp TEMP Start at this temperature. [unhelpful] |
| 270 | |
| 271 | |
| 272 | $Id$ |
| 273 | \f |
| 274 | Local variables: |
| 275 | mode: text |
| 276 | End: |