chiark - git - mdw - rocl/blob - DEVGUIDE

   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: