Introduction

If you plan on coding a larger area or combine multiple areas the organization of your code files becomes more and more important. So, spend a few minutes with planning your directory structure wisely. Furthermore it helps a lot if you create a directory structure similar to already existing ones - both QC Arches and yourself will appreciate it (for there's no doubt someone already thought about a good way how to do it). And that's what this article is about - to tell you how you could organize the files of larger areas in a convenient way.

General Issues

Icewind follows the philosophy that once an area (or any piece of code) has passed QC and has been included in the game (for an area it means the rooms are accessible to players) it will remain part of the game. Therefore area code will be moved from the wizards private directories into the area directory (/d). In general a wizard may request a sub-directory of /d for his area files. However, once the files are connected to the game it may be difficult to implement later changes for it is against the game rules to influence the players (this includes refreshing or updating of room files while players might be playing in these rooms). Hence, some general recommendations are:

1. Use a standard file and directory structure (see next section)
2. Code your area files 'movable' and do NOT hard-code file and path names!
   (more to that in the section Header Files)
3. Do not ONLY code in the area directory (/d/something)! Use a copy of the area during development (and moreover for testing purposes) and submit the changes progressivly to QC before updating the main area directory.
   (more to that in the section Updates)

Directory Structure

It should be clear that an area consist of multiple room-, item-, npc-files etc. Yet only the thought of putting all these files together in one directory would result in painful screams of horror amongst those who are not merely slaves of chaos :-). Having different sub-directories for different 'types' of files should be the logical conclusion. There are several possibilities of how to name your directories, here is one (and since I want you to use this structure - please DO name your directories as follows...)

The root directory of the area should only contain the MEMBERS file and a '.readme' file, which briefly explains the area and provides essential information.

The function files for rooms, NPCs, items etc. should be in the same directories as the files using them.

Header Files

It is essential to use header files for general setups of your area. This includes pathnames, exits to other areas etc. There should be one main header file containing these defines. The following example will illustrate such a file:

/* File         : cave.h
 * Description  : define file for cave area
 *
 * written      : 20-Nov-1999, Ghorwin@Icewind
 * last changes : 01-Aug-2000, Ghorwin@Icewind
 */

// include standard defines
#include "defines.h"

// defines for directories, if files are moved keep directory
// structure and only change AREA_ROOT define
#define AREA_ROOT           "/players/ghorwin/caves/"

#define CAVE_ROOMS          (AREA_ROOT + "room/")
#define CAVE_NPC            (AREA_ROOT + "npc/")

// defines for standard rooms/objects
#define I_CAVE              (CAVE_ROOMS+"std_cave")

// defines for exits to other areas
#define CAVE_EXIT_SOUTH     "/d/Grizzlypeaks/riverside_entrance"

As you can see a change of the directory structure or the root directory of the area is as easy as it could be - simply change the AREA_ROOT define or the appropriate directory define and that's it. Of course, this define file has to be included into each code file of your area via

#include "../header/cave.h"

DO NOT use complete pathnames for this include directive (e.g. "/players/ghorwin/caves/header/cave.h") (I don't have to explain why, right?).
Only relative path names should appear in your code files .

Updates

As explained above you should code your changes and additions to an already existing area in a seperate directory with the same directory structure. Once you're ready and the files can be submitted to QC you can simply write a new 'release' note in your QC directory listing the new files and anything else the QC arch should know. Once the files have passed QC these files may simply be copied into their new directories. Since a header file (like 'cave.h') already exists not even a single line in the sourcecode has to be changed - merely some defines in the global define-files have to be added or changed (that's cool, innit?).

Conclusion