Format of the initialization data file ('init_data')
Last updated: Jan. 20, 1999


The initialization data file is the most important file of all (other than
the program itself).  You can actually boot the program with just this file,
but without at least the userdata directory no users will be remembered.
This file contains a list of all the areas, their links and other important
information required for the program to initialize itself.

Note, this is the only file that can require you to reboot the talker for
changes to take effect. However, recent changes have meant that the only
items in the file which can't be changed on the fly are the port number
and the maximum numbers of areas allowed.

The format of this file has been completely changed from the format used
in the 2.3.0 version of NUTS. Its current format is more like that used
in the 3.x NUTS code.

The file consists of a series of lines in four distinct sections. Each line
can be either blank (ie. empty), a comment line, a section header, or contain
information used to set a specific program data item or limit. The four
distinct sections are:
        1. Data items and limits
        2. Area layout information
        3. Area topic strings        (optional)
        4. Special user information  (optional)

A comment is any line where the first non-blank character on the line is a
hash mark ('#'). Comments can be placed at the end of any other line as
long as it is separated by the preceding data by at least one space.
Comments at the end of a line do not need to be preceeded by a hash mark.

Each section within the initialization data file is marked by a section
header which defines the type of data which follows. The sections may be
in any order and need not appear at all (for sections marked as optional).
The section headers are single words immediately followed by a colon (':').
The four section headers in the order listed above (with the colon) are:
        1. init:
        2. areas:
        3. topics:
        4. users:


The 'init' section

Each line in this section contains two parts. These are a parameter and a
value. There are currently 36 different parameters that can be specified.
All parameters are optional, except for the parameter which specifies the
port number, and may be listed in any order. Default values will be used
for any of the parameters which are omitted from this section.

Parameter values may be a signed or unsigned number, a string of characters
not separated by spaces (spaces here refers to a any number of blank space
characters or tabs), user level strings, or a boolean value.

port        3000        # This is yet another comment which is ignored
#areas      50          Set maximum number of areas allowed (up to 200)
users       35          Maximum no. of users allowed on (not counting wiz)

level0      dunce       These strings are used to display a users level
level1      user
level2      wizard
level3      su
level4      *su*

login_trys  3

open_system      y
new_users        y
min_login_level  DUNCE
init_user_level  USER
no_logout_level  SU
login_show_level y
login_show_min   WIZARD

profile_lines    15
area_lines       15
echo_lines       15
tell_lines       15
log_lines        20
wiz_lines        20

atmosphere       y
bold_allowed     y
prevent_fakes    y
examines         n
whispers         n
ignores          n
user_ignores     n

heartbeat        30      Should be a multiple of 15 seconds
timeout_login    60      Should be a multiple of the heartbeat timer
idle_mention     5       Minutes of idleness for eyes to glaze over
idle_warn        15      Minutes BEFORE auto-logout to start warnings
idle_logout      30      Minutes of idleness before user is logged out
lifetime         21      Life of messages on message boards (in days)

logging          y


The 'areas' section

Each line of this section consists of 5 main fields (or bits) of information
about an area. These fields are the link code, area name, area status,
searchable flag, and area linkage. Each of these fields are single words or
groups of characters separated from each other by spaces excecpt for the
linkage information as noted below.

The first field is a link code which consists of from one to four characters
which will be used to refer to the area. These codes can be the first few
letters of the area name or just random characters. Its up to you but since
they are used in various places keeping them meaningful will help you in the
long run. Also, no two areas may have the same link codes.

The second field is the area name. This is the name by which users will
know the rooms. It is the label shown in the .look output under 'Exits:'.
and will be used by all users in .go commands.

The third field is the area status. It can be one of 6 values. These are
fixed, public, private, wiz_fixed, wiz_public, or wiz_private. The first
three and the last three are identical with the exception that the last
three are used for areas which are restricted to wizards. Regular users
can not enter these areas under any circumstances.

An area marked as fixed can never be changed. An area marked public can
be changed by users to private to prevent others from entering the area
without permission. An area marked private can only by users if they are
given permission or if the area is empty, a wizard can enter the area.

The fourth field is a boolean value that states whether the message
board for the area will be included as part of the messages searched
by a user when they use the .search command. Areas marked for wizards
only can not be searched by regular users regardless of the state of
this flag. You can list as many link codes as you like. There is no
limit except that the overall length of the line must not exceed about
4,000 characters (including spaces).

The fifth field is a list of area link codes separated by spaces. This
defines the areas a user can go to (ie. the exits) from the area named
on the line. Any area which does not need a link to another area will
not have any link codes. See the lines for the management and jail
areas in the example below.

Example of area information:
sq square fixed y rd pk
rd road public y sq
pk park public y sq
sh shop public n sq
mgmt management wiz_fixed n
jail jail jail n

A map for this place would look like this:
      +------+   +--------+   +------+
      | road |---| square +---+ park +
      +------+   +--------+   +------+
                     /\
      +------+    +------+    +------------+
      + jail +    + shop |    | management |
      +------+    +------+    +------------+

Ordinary users can go to the road, square, or park but to get to the shop
you must be a wizard (or higher level user), join someone already there or
be moved there by a wizard. From the shop there is a one way link back to
the square and there is no entrance or exit for the management or jail
areas. Only the message board of the road, square, and park areas may be
searched. The jail and management areas can not be made private. The
management area is accessible to wizards and up only. Ordinary users can
not enter the management area by any means.

The order that the rooms are listed is important as it defines the order 
that they are listed by the .areas command. You may choose to list them
alphabetically or list them in an order where nearby rooms are grouped
together. The latter may make it easier when you are comparing your map
to the areas information to check all the links between the areas are
correct. The first area listed is the area users first appear in when
they log in. This room must always be set to 'fixed'. The names of areas
is used as the name of the associated message board and atmosphere files.

NOTE: There is currently a limit of 200 areas imposed by a #define in the
code. This was arbitrarily chosen and can easily be changed by altering
'#define MAX_USERS' line in the code. The only real limit on the number of
areas is the amount of memory available.


The 'topics' section    (This section is optional)

This section must appear after the areas section as the parsing of this
section looks for valid area link codes. The area link codes would only
be valid after the areas section has been read.

Each line of the topics section consists of two parts. The first word must
be a valid link code for one of the areas defined in the areas section.
All characters found on the line starting from the first non-blank after
the area link code will be used for the area topic. Area topics will be
truncated as necessary to a maximum of 60 characters in length. 

NOTE: It is not necessary that all rooms have a default topic.


The 'users' section    (This section is optional)

This is a special section. It allows you to provide information on any
number of "special" users. Each line contains four parts. A user name,
user level string, password, and string to use as the users description.
When the talker is started, a check will be made to see that a data file
exists for each of the users named in this section. If no data file exists
for the named user, one will be created and the user level and password
will be set from the information provided.

Example line from users section:
fred        *SU*   test      is the caretaker of this place

This would result in a user data file being created when the talker is
started for Fred who will be given the user level of *SU*, a password
of 'test', and a description of 'is the caretaker of this place'.


Here is a sample initialization data file shown in full:

#Lines beginning like this one are comments and will be ignored.
init:                   This is also a comment and is ignored
port        3000        # This is yet another comment which is ignored
#areas      50          Set maximum number of areas allowed (up to 200)
users       35          Maximum no. of users allowed on (not counting wiz)

level0      dunce       These strings are used to display a users level
level1      user
level2      wizard
level3      su
level4      *su*

login_trys  3

open_system     y
new_users       y
min_login_level DUNCE
init_user_level USER
no_logout_level SU
login_show_level y
login_show_min  WIZARD

profile_lines   15
area_lines      15
echo_lines      15
tell_lines      15
log_lines       20
wiz_lines       20

atmosphere      y
bold_allowed    y
prevent_fakes   y
examines        n
whispers        n
ignores         n
user_ignores    n

heartbeat       30      Should be a multiple of 15 seconds
timeout_login   60      Should be a multiple of the heartbeat timer
idle_mention    5       Minutes of idleness for eyes to glaze over
idle_warn       15      Minutes BEFORE auto-logout to start warnings
idle_logout     30      Minutes of idleness before user is logged out
lifetime        21      Life of messages on message boards (in days)

logging         y


areas:
sq square fixed y rd pk
rd road public y sq
pk park public y sq
sh shop public y sq
mgmt management wiz_public n
jail jail jail n


#This section lists special user accounts. If accounts don't exist for these
#users at boot time they will be created automatically. This protects names 
#used by the people who run the talker and ensures their name can never be
#taken by some other general user.

users:
fred        *SU*   test      is the caretaker of this place