What is a level set?
====================

	A level set is a sequence of levels.  The user starts at the 
	first level.  If they complete a level successfully they move
	on to the next one.  There are also some settings, such as the
	way lives work.  You can let the user choose to jump to a later
	level by supplying a password for that level.


How does it work?
=================

	To load a level set in the game, you specify the name of the 
	index file.  The index file contains the title of the set, the
	name of its compiler, the list of levels to play, the passwords 
	(if any), and the additional settings such as life rules.
	
	The map files themselves are stored separately; the index file
	just gives a path to them, relative to its own directory.
	
	Alternatively, you can put all of these files in an Allegro 
	datafile, including the index.  This makes your level set
	completely self-contained; the user specifies the name of the 
	datafile to load the level set.


The index file
==============

	The index file is basically a plain text file (DOS or Unix 
	format), but it can be packed with Allegro's packing routines.
	
	It must start with "R3PC level set" followed immediately by a
	newline.
	
	After that you make various settings.  Lines beginning with `#'
	are comments, which are ignored.  Lines longer than 128 
	characters are ignored too.  Settings are of the form:
	
		option=value
	
	The syntax of `value' depends upon what `option' is being set.
	Here is a list of valid options:
	
		title=<string>
			Sets the title of the level set.  Max is 40 chars.
		
		compiler=<string>
			Sets the compiler of the level set.  That's you.
		
		lives=<number>|<string>
			Describes how lives will work in this level set.  If
			you specify a number, the player gets that number of
			lives at the start, with which to complete all of the
			levels.  Otherwise, options are:
			
				infinite:  Unlimited lives
				   level:  Use the values stored in the maps; 
				             surplus does not carry over from 
				             level to level
				    auto:  Start with zero; on entering a level,
				             add on that level's quota
			
			Those are the only valid strings.
		
		levels=<number>
			This is the total number of levels in the set.  It must
			come before any level definitions.
		
		level=<string>[,<string>]
			The first string is the relative path and filename of 
			this level.  The second string (which is optional) gives
			the password to skip to this level.  You should put in
			one "level=" setting for each level in the set.
		
		endtext=<number>
			This specifies the number of following lines which make
			up the `end text', which is displayed when the player
			completes the last level.  Write the text itself on the
			next <number> lines; in the game they'll be catenated
			and separated by a single space.
	
	See the index file for the "learning" level set, located in 
	"data/levels/learning" for an example of what to do.


Using a datafile
================

	To put your maps and index into a datafile you must use the 
	Allegro utilities as shown below.  I might get around to making 
	a program to automate this one day.

	1) Uncompress everything
	~~~~~~~~~~~~~~~~~~~~~~~~
		When a compressed file is stored in a datafile it cannot
		be read in the normal way, so you must ensure that all your
		map files are uncompressed.  By default the map editor
		compresses the files; load them and turn off compression
		in the level options (press 'O' then 'L').  You can compress
		the datafile in the end anyway, so there's no loss here.
		
	2) Put the maps in a datafile
	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
		Use the Allegro `dat' utility to make your datafile, adding
		your uncompressed maps.  It's best to give the `-k' switch,
		to prevent `dat' from mangling the object names as it adds
		them; this simplifies writing the index file.
	
	3) Touch up the index file
	~~~~~~~~~~~~~~~~~~~~~~~~~~
		As far as Repton is concerned, all the maps are in the same
		directory as the index file.  If they weren't before, you'll
		have to alter the index file to remove the relative paths.
		If the maps were always in the same directory as the index 
		file, you won't need to do this.
		
		However, if you didn't specify the `-k' switch to the `dat'
		utility in step 2, you should note that what you need to
		give in the index file is the object's NAME property in the 
		datafile.  Typing "dat -l myfile.set" will tell you the 
		names of the objects (in the second column).
	
	4) Add the index file
	~~~~~~~~~~~~~~~~~~~~~
		Use the `dat' utility now to add the index file to the 
		datafile.  Make sure its name is "index".  I recommend
		making the index file's filename "index" and using the
		`-k' switch to `dat' again.  Alternatively:
		
			dat NAME=index myfile.set indexfile.txt
	
	5) Try it out
	~~~~~~~~~~~~~
		Load up Repton, and try to load your datafile into the 
		game.  When it's loaded, also check that you can play it
		-- the individual maps aren't checked until you try to 
		play them.


Possible problems
=================

	The error messages aren't very detailed at the moment, so it
	might be hard to figure out why your set isn't working.
	
	If you are trying to make a basic set, i.e. a few .map files
	and an index file, then test the maps separately first.  If
	they work then you probably made a mistake in the index file;
	check it carefully.  In particular, ensure that settings aren't
	done more than once (excepting "level=" settings), that the
	"levels=" setting comes before any "level=" settings, and that
	you don't have too many "level=" settings.  Having too few is 
	bad too because the game will probably crash when you try to
	play them.
	
	If you're making a datafile, first make sure your set works as
	separate files.  If it doesn't, fix that first.  Then make
	sure you're uncompressing the maps before adding them to the
	datafile.  If you forget to do this, they won't load properly
	(you'll probably see a lot of map loading errors).
	
	It's much easier to make the datafile if you first get it working
	as a multi-file set with all the files in the same directory.  In
	this case you don't need to edit the index file for the datafile
	version, provided you use the `-k' option to `dat'.
	
	You can try to play individual levels from your datafile by 
	loading them as "myfile.set#thelevel.map".
