
                             Return To Chaos
                             ---------------

                          Dungeon Editing Guide
                          ---------------------


This file outlines the simple steps required to create your own new dungeons
for Return To Chaos (hereafter RTC).

I have tried to design the format itself to be as intuative as possible to use, 
however if there are any issues which are unclear or any other feedback you wish
to give please do not hesitate to leave a message at either the RTC main-web site:

	http://www.ragingmole.com/RTC

or the support forum:

	http://www.dungeon-master.com/forum/ 


Overview
--------
New RTC dungeons are defined in ASCII text files requiring you to have no more 
than a simple editor (e.g. Notepad) to create your own dungeons. 

Included in with this distribution is a simple GUI editor for the text files
(RTCEditor.exe). I have always seen the text format as an intermediate step and 
by making the dungeon format public it allows third parties to create their own 
GUI editors with the aim of giving a better graphical method of dungeon creation
and sparing the casual user from the low level details.

It is not intended that users create their own dungeons from scratch - it is
far easier to learn by example and as such the source RTC text files for Dungeon 
Master et al. are included with this distribution. It is highly recommended that 
you examine these files carefully before attempting to create a new dungeon.

Throughout please remember that ALL FILES FOR USE WITH RTC ARE TAB-DELIMITED.


Compiling A Dungeon
-------------------

Once you have a dungeon in the text format it can be compiled into an RTC module
by including a COMPILE instruction into the "config.txt" file of the main game. 
This instruction takes a single parameter, the filename (including any 
sub-directories) of your dungeon - for example:

COMPILE		Modules\New\MyDungeon.txt

Remember that ALL FILES FOR USE WITH RTC ARE TAB-DELIMITED so the gap between 
the "COMPILE" and the filename is a tab and not lots of spaces. Alternatively
you can specify the name of the dungeon as an additional command line parameter
when starting RTC - for example:

RTC.exe Modules\New\MyDungeon.txt

The value given on the command line will over-ride any given in the config file.

The next time you run the game the engine will then attempt to compile and run 
your dungeon. After the introduction sequence a menu screen will appear giving 
a summary of the compilation including the number of errors and warnings found
(see below) - a more detailed description of any problems is written to a log 
file in the same directory as the text file (for the above example this would 
be Modules\New\MyDungeon.log). 

- Errors are normally a result of typos in the text file or the incorrect syntax 
  of a line. Examples of errors include mis-spelling an object or instruction 
  so that it can not be recognised by the interpreter or omitting a key property 
  from an item definition.

- Warnings are normally a result of inconsistencies in the dungeon layout. 
  Although they usually indicate something is wrong it may be that you intended 
  the dungeon to be this way and as a result the RTC engine will create a dungeon 
  exactly as you have specified it. Examples of warnings include teleporters which
  point into walls, doors without doorframes or a staircase down on one level 
  without a corresponding staircase up on the next level. 

Regardless of the number of errors or warnings, RTC will then display the dungeon 
entrance and you are ready to enter and test your dungeon. The game will try and 
cope with any errors that it finds, but you should remember that it is very likely 
that your dungeon will not appear as expected and the game may abort at any point. 
As such, a compiled version of your dungeon (e.g. Modules\New\MyDungeon.rtc)
will only be created if there are no errors. 

Alternatively, if you only want to test your dungeon (as opposed to compiling it
into an *.rtc file), you can specify the "TEST" instruction in the config.txt file.
This instruction is used in the same way as the "COMPILE" instruction (i.e. followed
by a tab and then the name of the dungeon text file) and will load and allow you
to play test the dungeon without compiling it.

After fully testing your dungeon and then compiling it, as the final step, remove 
the COMPILE instruction from your config.txt file. When you next re-start the game 
your new dungeon will be available for selection from the main start-up menu and 
is ready for distribution to other players. As the compiled files can not be viewed 
or edited, to preserve the mystery of your new dungeon, it is recomended that you 
only distribute the compiled *.rtc file to others. Equally, it is vital that you 
do not delete your copy of the text file as the only way to make modifications to 
the dungeon is to alter that file!

Have fun...

	George Gilbert
	(May 2008)
