===========================================================================
                          Modifying LuxMan
===========================================================================

This file documents how to modify LuxMan from an external point
of view. That is, this file tells you how you can change the game
without recompiling the source code.

===========================================================================
 Level files:
===========================================================================

A level file is a text file which describes the playing order
of a game. The level files included with LuxMan are `levels.def'
and `old.def'. These files have a very simple structure. They
are simply a collection of bracketed sections of the form:

{
	maze = m1.map
	tile = tile14.map
	fruit = cherry.map
	depth = 18
	regen_wait = 200
	fruit_val = 100
	fruit_quota = 10
	bg = BLACK
	dot = YELLOW
	bigdot = YELLOW
	ghost_blue = 100
	ghost_flash = 60
	lux_body = YELLOW
	glasses = BLACK
}

Not all parameters are required. They may be listed in any order.
You may have as many levels in the level file as you wish. All
unrecognized lines are ignored.

Here is a description of all settable parameters:

Name		Type		Description
----		----		-----------
maze		filename	Name of bitmap to use for maze.
tile		filename	Name of bitmap to use to paint walls.
fruit		filename	Name of bitmap to use for fruit.
depth		integer		Search depth for eyes (finding path to home).
regen_wait	integer		Number of frames for eyes to wait (after
				they get home) before regenerating.
fruit_val	integer		Point value of fruit.
fruit_quota	integer		Maximum number of fruit allowed to appear
				per life (i.e. if you get killed it is
				reset).
fruit_off	integer		Number of frames for fruit to stay off.
fruit_on	integer		Number of frames for fruit to turn on.
bg		COLOR		Background color of screen.
dot		COLOR		Color of dots.
bigdot		COLOR		Color of `power pills'.
ghost_blue	integer		Number of frames for ghosts to remain blue.
ghost_flash	integer		Number of frames for ghosts to flash.
				(i.e. the total energized period =
				 ghost_blue + ghost_flash)
lux_body	COLOR		Color of LuxMan body
glasses		COLOR		Color of LuxMan sunglasses

Here is a description of the data types:

Type		Description
----		-----------
filename	Any legal filename. Not surrounded by quotes.
integer		An integer.
COLOR		One of the following strings:
		    BLACK, BLUE, GREEN, CYAN, RED, MAGENTA, BROWN,
    		    LIGHTGRAY, DARKGRAY, LIGHTBLUE, LIGHTGREEN,
		    LIGHTCYAN, LIGHTRED, LIGHTMAGENTA, YELLOW,
		    WHITE

Here are the default values for each parameter:

Parameter	Default
---------	-------
maze		None	(REQUIRED PARAMETER)
tile		None	(REQUIRED PARAMETER)
fruit		None	(REQUIRED PARAMETER)
depth		None	(REQUIRED PARAMETER)
regen_wait	0
fruit_val	100
fruit_quota	100
fruit_off	200
fruit_on	200
bg		BLACK
dot		YELLOW
bigdot		YELLOW
ghost_blue	100
ghost_flash	60
lux_body	YELLOW
glasses		BLACK

========================
 Checking a level file:
========================

If you modify a level file, it is VERY important that you check
the modified file with the program `luxchk'. The basic usage
is:

	luxchk levels.def

(Assuming the file is named `levels.def').

This will check that all required parameters are there, and,
more importantly, it will make sure that the search depth
you specified for each level is sufficient.

If you do not check the file with luxchk, LuxMan may
abruptly exit (even during a game!) which is sort of ugly.

luxchk expects to find:
 (1) the level file in the current directory
 (2) bitmap images (fruit, ghosts, etc.) in a subdirectory
     `maps' under the current directory
 (3) mazes in a subdirectory `mazes' under the current subdirectory

===========================================================================
 Scenarios File:
===========================================================================

A scenarios file is a text file describing all the level files
you want to be able to choose from in a game. The default
scenarios file is named `scenarios'. It is pretty self
explanatory:

(Begin included file)
#
# This is a scenarios file.
#
# The format is very simple - lines of the form:
#
# |description|filename|base_dir|
#
# `description' may be any string (excluding |'s).
# `filename' must be the name of a level file.
# `base_dir' is the directory under which LuxMan expects to
#  find:
# 	(base_dir)/fonts
#	(base_dir)/maps
#	(base_dir)/mazes
#	(base_dir)/11k
#
#  `base_dir' may be a list of paths to check, e.g.:
#	`.:/usr/lib/games/luxman/my_scenario'
#
# The level file must be in (base_dir).
#
|Modern|levels.def|.:/usr/lib/games/luxman/modern|
|Original (0.26)|old.def|.:/usr/lib/games/luxman/oldscen|

(End of included file)

The scenarios file may be located either in the current
directory or in /usr/lib/games/luxman.

-f
--

The -f parameter tells LuxMan what filename to use as the scenarios
file. The default is `scenarios'. If you make a new scenarios file,
say, `scen2', you would just say:

	luxman -f scen2

====================================================================
 Mazes:
====================================================================

A maze is a simple bitmap. These can be edited using the program
`maped', located in the `gtools' subdirectory of the main lux
source tree. `maped' requires a mouse.

Various maze elements are color coded as follows:

Element		Color(s)
-------		--------
Ghosts		Lightblue, Red, Magenta, Green (all 4 required)
LuxMan		Cyan
Tile (wall)	White
No dot		(Transparent)
Ghost home	Darkgray
Bigdot		Yellow
Fruit		Lightred

A few notes:
------------
(1) Dots are placed EVERYWHERE except:
	(a) LuxMan location
	(b) Tile locations
	(c) Bigdot (power pill) location
	(d) Ghost home
	(e) Squares marked with `No dot' color.

(2) The `transparent' color is the color located on the right side
    of the screen in `maped', just above the main 16-color palette.

(3) If no `fruit' location is specified, it will default to the
    LuxMan location.

====================================================================
 Images:
====================================================================

The tiles, ghosts, luxman, fruit and home tile are just bitmaps.
You can edit them, or create new ones with the program `maped'
in the `gtools' subdirectory. `maped' requires a mouse.

====================================================================
 Directory structure:
====================================================================

Just to put all of this in one place, the directory structure is
documented here.

Scenarios files:
	The current directory is searched first, followed by
	/usr/lib/games/luxman.

Level files:
	These are expected to be in the `base directory' specified
	in the scenarios file.

Bitmaps (tiles, images, fonts):
	These should be found in a subdirectory called `maps'
	underneath the `base directory' given in the scenario
	file.

Mazes:
	These should be located in a subdirectory called `mazes'
	underneath the `base directory' given in the scenario
	file.

Sounds:
	The subdirectory `11k' underneath the current directory
	is searched first, followed by /usr/lib/games/luxman/11k.

For an example, see the directory /usr/lib/games/luxman/modern
(this requires that you install LuxMan).

====================================================================

If you spot any bugs in this document, or have suggestions for
improvements, send mail to:

frankm@nuance.com