Make the fuel metric be lightyears, not decilightyears. Make summary

[rocl] / README

RIGHT ON COMMAND-LINE
  Elite tools for the discerning player

1. Installation

	You need a C compiler and a working Tcl/Tk installation.  (The
	elite-editor program needs Tk; the rest of the tools don't.)
	The Makefile works on my Debian GNU/Linux box (potato), but I'm
	not making any promises about anyone else's.  I've successfully
	built earlier versions of everything under Cygwin, against
	ActiveState's Tcl 8.4, but I've forgotten the Holy Runes.  I do
	have the `.def' file I used to build the DLL, though, for
	whatever that's worth.  (If you want to hack the Makefile to
	work under Windows, I'll take a patch.)

	The runes for Debian woody are:

	  $ make INCLUDES=/usr/include/tcl8.3
	  $ ROOTLY make install prefix=/usr

	(where ROOTLY is some command which does things with root
	privileges, say `sudo', `become root' or, at a pinch, `su -c')
	because the Tcl installation no longer looks in /usr/local/lib,
	worse luck.

	The theory is that you should edit the Makefile for your system
	and say `make'; then, as some suitably privileged person, say
	`make install' and stand well back.  Everything should then be
	installed.

	In practice:

	  * If you can't build `pkgIndex.tcl', run `tclsh' and say

	      % pkg_mkIndex -verbose -direct . elite.so elite.tcl

	    to it.  (Use `elite.dll' if you're on Windows.)  Say

	      % set tcl_pkgPath

	    to see a list of suitable places for putting the kit.  Pick
	    one.  The directory `/usr/local/lib' appears in my
	    installation, so that's what I use.

	  * Make a subdirectory in the place you chose, and copy
	    `elite.so', `elite.tcl' and `pkgIndex.tcl' into it.  All
	    should now be hunky-dory.

	  * Run (say) `elite-describe lave' to check that things are set
	    up properly.


2. The command-line tools

	A `galaxy-spec' is

	  * a number, between 1 and 8, for one of the standard eight
	    galaxies; 

	  * a `galaxy seed' of 12 hex digits (a 48-bit value), for any
	    arbitrary galaxy; or

	  * a string `SEED:N' where SEED is a galaxy seed and N is a
	    number between 1 and 8, for the Nth galaxy in some custom
	    universe.

	A `planet-spec' is interpreted relative to some parent galaxy.
	It may be

	  * a number N, for the Nth planet in the galaxy (planets are
	    numbered pseudorandomly -- this is not often a helpful
	    option);

	  * a `planet seed' of 12 hex digits (a 48-bit value), for any
	    arbitrary planet;

	  * a pair of numbers `X,Y', for the planet nearest the point X
	    decilightyears rightwards and T decilightyears down from the
	    top left of the galaxy;

	  * a glob pattern (a string containing `*' and `?' wildcards,
	    matching any substring or any single character,
	    respectively), for the first planet whose name matches the
	    pattern; or

	  * a string `GAL:P', where GAL is a galaxy-spec and P is a
	    planet-spec, for the planet P in galaxy GAL.


  elite-describe [-g GAL] PLANET ...

	For each PLANET, print the planet data for that PLANET.  The
	PLANETs are interpreted relative to GAL, or standard galaxy 1 if
	GAL is not specified.


  elite-map [-qv] [-g GALAXY] [-d DIST] [-w WEIGHT] [-W WD,HT] [-a ASP]
	[PLANET ...]

	Prints a map of (part of) a galaxy to the terminal.

	If PLANET is specified (which it usually is), a map of the area
	around PLANET in GALAXY (default standard galaxy 1) is printed,
	showing other planets within a box extending about DIST
	lightyears around the PLANETs.

	If no PLANETs are not specified, the entire galaxy is printed.
	This is usually unhelpful.

	The `-w' option plots a route through the listed planets,
	highlighting the waypoints.  See `elite-path' for the possible
	weightings.

	Planets are shown as numbers or letters (or, occasionally a
	sequence of letters).  If there is only one PLANET, it is shown
	as a `*'; otherwise, they're labelled `*0', `*1', etc.  Planets
	on the path are labelled `+0', `+1', ..., in the order you're
	meant to visit them.  (Note that if the path doubles back on
	itself, the planets involved /won't/ be listed twice.  Use
	`elite-path' for a full guide on where to go, and `elite-map' to
	visualize the route.)

	The `-q' and `-v' options allow optional suppression of the key
	below the map.  The defaults are as follows:

	  * A galactic map shows no key.

	  * A route map (with the `-w' option) shows the waypoints
	    (named PLANETs) and the planets on the path.

	  * An area map (around named planets) shows the names of all
	    planets shown.

	The key can be made more verbose by giving the `-v' option, or
	less verbose by `-q'.  Note that the options parser is currently
	really shoddy, and won't let you say things like `-qqq'.

	The size of the map may be controlled by the -W option -- set WD
	to the maximum allowable width, and HT to the maximum allowable
	height (in columns and rows, respectively).  The map will be
	scaled so as to fit.  The -a option sets the aspect ratio of
	your characters, height to width (the default is about 2, and
	seems right for viewing in an xterm with the standard fixed
	font).



  elite-path [-g GALAXY] [-w WEIGHT] [-a ACC] PLANET PLANET ...

	Computes a route through a GALAXY (default is standard galaxy
	1), starting at the first PLANET listed, via the second, via the
	third, etc., and ending at the last.  For each planet you're
	meant to stop at on the way, a summary line is printed giving
	the planet's name, position, government type, economy type and
	tech level.

	You can affect how elite-path selects its routes using the `-w'
	option.  The default is to minimize the number of hops.  Other
	possibilities are:

	hops		Minimize number of hops.  This is the default.

	safety		Maximize stability of the planets in the route,
			to attempt to improve safety.  Useful during the
			early stages of the game.

	encounters	The opposite of `safety' -- minimizes stability
			of planets in the route.  Useful if you want to
			maximize kills.

	trading		Maximize the difference in economy type between
			successive planets in the route.  This should
			give you an opportunity to make a good profit as
			you go.

	fuel		Minimize absolute distance.  For those on a
			tight budget.

	The `-a' option controls what total is accumulated down the
	right hand side of the summaries:

	none		No running total down the right hand side.

	distance	Accumulate distance, in lightyears.

	weight		Accumulate the shortest-path weight function.

	Beneath the path is printed a total for distance and weight if
	these are interesting and not already displayed.  The weight for
	`hops' and `fuel' are simply the hop count and distance in
	lightyears respectively; the other weight functions use
	appropriate square-law functions.


  elite-reach [-d DIST] [GALAXY ...]

	For each GALAXY (default is the 8 standard ones), print summary
	information for each planet, with blank lines separating
	disconnected groups of planets, i.e., groups where a ship
	capable of travelling DIST lightyears (default 7) can't get from
	one to the other.


  elite-find [-g GALAXY] [EXPR]

	Without EXPR, simply prints summary information for each planet
	in GALAXY (default standard 1).

	If EXPR is specified, it must be a Tcl expression (as for the
	`expr' command).  Information is printed for each planet for
	which EXPR returns nonzero.  The EXPR may use the following
	variables:

	name		The planet name, with initial capital letter.

	x, y		X and Y coordinates, from top left, in
			decilightyears.

	economy		From 0 (rich industrial) to 7 (poor
			agricultural).

	government	From 0 (anarchy) to 7 (corporate state).

	techlevel	From 1 to 15.

	radius		In kilometres.

	productivity	In millions of credits.

	population	In hundreds of millions.

	inhabitants	A Tcl list of words describing the inhabitants.

	description	As a Tcl list of words.


  elite-pairs [-g GALAXY] [-d DIST] AEXPR BEXPR

	Prints the names of pairs of planets A and B in GALAXY (default
	standard 1), no further than DIST (default 7) lightyears apart,
	such that AEXPR returns nonzero for planet A and BEXPR returns
	nonzero for planet B.

	The expressions AEXPR and BEXPR may use the same variables as
	for elite-find.  In addition, BEXPR may use

	d		The distance between planets A and B.

	a		An array containing the information about planet
			A.  The indices have the same names and meanings
			as the variables described above.


  elite-cmdr [FILE] [-OPTION | ATTR | ATTR=VALUE | FILE] ...

	A command-line Elite commander editor and viewer.  With a single
	argument, reads a commander file and displays its contents as a
	human readable table.  The arguments may be special options,
	attribute names, attribute assignments, or filenames.

	The special options are:

	-show		Write the commander data to standard output as a
			human-readable table.  This is the default if no
			other output action is requested.

	-load FILE	Read the commander file named FILE.

	-save FILE	Write the modified commander data to FILE.

	-reset		Reset the commander to the default `JAMESON'
			settings.

	-dump		Write the commander data to standard output in
			the form of a script which can be read back by
			the `-read' option.

	-read FILE	Read attribute/value pairs from FILE, and modify
			the commander accordingly.

	An attribute name on its own is a request to print the current
	value of that attribute.  An assignment ATTR=VALUE makes ATTR
	have the requested VALUE.

	The attributes, their meanings, and the acceptable values are as
	follows:

	mission		The commander's current mission.  (0 is no
			mission; 1 is searching for the Constrictor; 2
			is killed the Constrictor; 3 is waiting for the
			second mission; 4 is heading for Ceerdi; 5 is
			heading for Birera; and 6 is all missions
			completed.)  Must be an integer between 0 and
			255.

	score		Current number of kills.  Must be an integer
			between 0 a 65535, or one of the strings
			`harmless', `mostly-harmless', `poor',
			`average', `above-average', `competent',
			`dangerous', `deadly', or `elite'.

	credits		Number of credits.  Must be between 0 and
			429496729.5.

	cargo		Size of cargo bay.  Must be between 4 and 255.

	gal-number	Number of the current galaxy.  Note that this
			doesn't affect which galaxy the commander is
			actually in -- set gal-seed for that.  Must be
			between 1 and 8.

	gal-seed	Which galaxy the commander is in.  May be any
			galaxy-spec.

	world		Which world the commander is docked at.  May be
			any planet-spec describing a world in the
			correct galaxy.  (Note that, since the commander
			file actually stores the location as an x, y
			pair and chooses the closest world to those
			coordinates, and there are coincident pairs of
			worlds, it is not possible to have a commander
			start at some worlds.)

	market-fluc	The market fluctuation byte.  Affects prices at
			the space station.  Must be an integer between 0
			and 255.

	fuel		Amount of fuel.  Must be between 0 and 25.5.

	energy-unit	Strength of the ship's energy unit.  May be an
			integer between 0 (none) and 255 (scary cheat)
			or one of the strings `none', `standard', or
			`naval'.

	front-laser, rear-laser, left-laser, light-laser
			Strength of appropriate laser.  May be an
			integer between 0 (none) and 255 (scary cheat)
			or one of the strings `none', `pulse', `beam',
			`mining', or `military'.

	ecm, fuel-scroop, enery-bomb, escape-pod,
	docking-computer, gal-hyperdrive
			Whether the ship has various bits of equipment.
			One of `yes', `true', or `on' for yes, or `no',
			`false' or `off' for no.

	missiles	Number of missiles carried.  Must be an integer
			between 0 and 255.

	hold-ITEM, station-ITEM
			Quantity of some item in the ship's hold, or at
			the station.  Must be an integer between 0 and
			255.  ITEM must be one of `food', `textiles',
			`radioactives', `slaves', `liquor-wines',
			`luxuries', `narcotics', `computers',
			`machinery', `alloys', `firearms', `furs',
			`minerals', `gold', `platinum', `gem-stones', or
			`alien-items'.

	#		A special attribute which is never printed.  Its
			value is ignored.  This may be used to insert
			comments in script files.

	Anything else is assumed to be a filename, and loaded as for the
	`-load' option.


  elite-prices [-g GALAXY] [-s SORT] [FROM TO]

	Shows minimum, average and maximum profit (in that order, in
	credits per unit) for the various commodities, starting at one
	kind of world and ending at another.

	By default, the commodities are listed in standard order, and
	the profits are computed going from a poor agricultural world to
	a rich industrial one.

	You can change the worlds under consideration by typing a pair
	of planet-specs or economy types (as printed by `elite-find').
	Any planet-specs are obviously taken relative to GALAXY.

	The SORT parameter may be one of `min', `max', or `avg' to sort
	by minimum, maximum or average profit (highest at the top).


3. The graphical editor

  elite-editor [GALAXY | FILE | -jameson]

	Starts the RIGHT ON COMMAND-LINE Commander Editor and Map.  This
	is a Tk program -- you'll need that installed to run it.

	I'll not go into excruciating detail about how to work the
	program.  It's fairly simple, really.

	The map view lets you colour-code planets according to
	techlevel, government or economy.  The colours ought to be as
	follows:

	Colour		Government	Economy		Techlevel

	Red		Anarchy		Poor agri	1
	Orange		Feudal		Average agri	2 or 3
	Yellow		Multi-gov	Rich agri	4 or 5
	Green		Dictatorship	Mainly agri	6 or 7
	Blue		Communist	Mainly indust	8 or 9
	Magenta		Confederacy	Poor indust	10 or 11
	Violet		Democracy	Average indust	12 or 13
	White		Corporate	Rich indust	14 or 15

	The connectivity map shows how you can get around the galaxy
	using hops of up to 7 light years.

	Planet names are unhelpful except at small scales.  The
	placement algorithm could do with a lot of work.

	Clicking on the map with button 1 (usually the left one) sets
	the destination world, marked with an orange cross.  Clicking
	with button 3 (usually the right one) sets the home world,
	marked with a red cross, and with a green hyperspace-range
	circle around it.  (The circle doesn't actually correspond
	exactly with hyperspace reachability, because there are rounding
	errors in the distance computation.  ROCL correctly emulates the
	rounding errors from the original game.)

	Double-clicking opens a window showing information about a
	planet.  Two info windows can be open at any time, one for the
	home world and one for the destination.

	The bar along the bottom of the map window shows the names of
	the home and destination worlds, and the distance between them.
	You can type new names (or any old planet spec) into either to
	select different planets.  The change will take place when you
	press return or when the input focus moves.  Pressing control-
	return will pop up the appropriate planet info window.

	The `Compute path' lets you do the same kinds of computations as
	the elite-path tool.  It plots a route from the home to the
	destination.  The path is shown in orange on the map.

	The commander editor should be self-explanatory, but maybe a few
	pointers might be helpful.

	The entry fields for items with pop-up menus are disabled when
	the menus show values other than `Custom', so you must first
	choose `Custom' from the menu if you want a fancy value.

	The `Show galaxy map' button opens a map which will be tied to
	the commander window.  When you select a home world (button 3),
	this will set the world where the commander will start.  Note
	that the market prices (in the `Cargo' window) update
	automatically as you move about the universe.  It is quite
	possible to travel about entirely new universes by turning off
	the `Standard galaxy' button and typing some hex number into the
	`Galaxy seed' box.  All of the ROCL tools work in these custom
	universes.  Note that your docked planet is recorded as an x, y
	coordinate pair, so Elite can't tell which of two coincident
	planets you're docked at (yes, there are such pairs).  ROCL
	won't cope with this at the moment.

	Lasers are a bit odd.  Bit 7 is a `rapid-fire' bit.  It doesn't
	affect the strength of the laser, but means that there's no
	delay between shots.  The low 7 bits control the strength, but
	without the rapid-fire bit, powerful lasers will tend to fire
	more slowly than weak ones.  Some comparisons in the program are
	for exact laser power: you can't damage the Constrictor or
	Cougar ships unless you have military (or 0x17 slow-firing)
	lasers; and you can't fragment asteroids unless you have mining
	or 0xb2 rapid-fire lasers.  (The 0xb2's pack a serious punch.  I
	recommend them as an upgrade for commanders who don't wish to
	cheat completely.)

	One suggestion I've heard of, if Elite is too easy, is to start
	at Lave (as usual), with no money, lasers, missiles, or fuel.
	You can get your first money by ramming asteroids (easy but
	unrewarding) or pirates (risky and tedious), and start trading
	food and other cheap items.

$Id: README,v 1.6 2003/03/04 10:25:43 mdw Exp $
\f
Local variables:
mode: text
End: