DOMAINS
                                    ~~~~~~~
                              (Updated 93.07.22)

Introduction
~~~~~~~~~~~~
The TMI-2 mudlib comes with a series of features which are all tied
together under the heading of domains.  These features allow you to
organize your playing areas and your wizards together into groups,
with a clear hierarchy of permissions and responsibilities, which is
designed to let you organize your MUD more efficiently and more
productively.


What is a Domain?
~~~~~~~~~~~~~~~~~
A domain refers to two objects:  first, a subdirectory of "/d", and
second, the wizards whose code is stored in that directory.  Although
you may handle the organization of your world in any way you like,
most MUDs find it convenient to divide the world into smaller units
and organize the room files so that rooms in the same domain are placed
together in the same subdirectory of "/d".  For example, you might
have three domains in your MUD: `Northlands', `The Barren Desert',
and `The Black Forest'.  Given those, you might want to create three
subdirectories in "/d": call them "/d/northlands", "/d/desert", and
"/d/forest".  The main areas of each domain can be placed in these
directories, with appropriate rooms having exits to each wizard's area
in his home directory.

The default mudlib comes with three domains: `Fooland', which has the
base world, `grid', which is an example of the virtual room facitily, and
`std', which contains the void room.  You can remove `Fooland' and/or `grid',
but do not remove `std' since several parts of the lib rely on "/d/std/void.c"
to exist, to store objects temporarily while rooms are updated or other
disturbing things take place.


Domain Files
~~~~~~~~~~~~
Each domain must contain a subdirectory "adm", i.e. "/d/Fooland/adm".
In this directory, there must be a domain master file ("d_master.c"),
which controls the permissions that people have to write to that
domain.  You should give write access to "/d/<domain name>/adm" to
the head wizard of that domain (hereafter called the domain lord).
Then the domain lord can alter the domain master file to give write
access to other parts of "/d" to those wizards who have areas in that
domain.  This permits you to appoint domain lords without giving them
global access to all files, since they can control permissions within
their domain without accessing "/adm/etc/access" (and the rest of "/adm").
This is desireable because it means domain lords don't have to have admin
permissions, which is useful if you have a lot of wizards, and hence a lot
of domains, but don't want 25 people to have admin access. If you make a
new domain directory, be sure to add it to the #define DOMAIN_DIRS in
domains.h, so that the master object will know to check the domain
master when handling file permissions for the domain directory.

    
Domain Groups
~~~~~~~~~~~~~
The term "domain" also refers to the particular group of wizards who
code the areas in that domain's chunk of the world.  The following
commands are provided:

    o   sponsor -- Assign a wizard to a domain, or promote a wizard
                   within his/her domain.  Wizards may be appointed
                   to more than one domain.

    o   demote  -- Demote a wizard within his/her domain.

    o   people  -- Show the domain of each user and his rank within
                   that domain.

    o   domains -- Select which of the user's domains will appear in
                   the "people" command.

The available ranks (LEVEL_LIST) are defined in "domains.h", where the
default values are "guest", "seeker", "novice", "apprentice", "initiate",
"adept", and "sage".  You're welcome to change these to anything you want.
You should also alter "domains.h" to reflect the different domains within
your lib (DOMAIN_LIST).  Players will show up on the people list as "player"
rank in "None" domain. Unaffiliated wizards will appear as "guest" rank,
also in "None" domain. Other wizards will have their rank and domain
affiliation shown.

Note:
    Domain rank does not control any permissions or powers whatsoever--
    it is used purely to organize wizards into teams.  The only exception
    is that you must be sage rank in a domain to promote someone within a
    domain. (Though admins can promote anyone in any domain.) You may
    want to alter the level at which a wizard can promote within the
    domain: you can alter the #define MIN_SPONSOR_LEVEL in domains.h to
    do that.

    A one-to-one correspondence between domain directories and domain
    groups is not necessary.  You can create domain groups that will
    help organize your wizards not tied to a specific domain.  For
    example, you may edit the DOMAIN_LIST in "domains.h" to include the
    following organizational groups: "mudlib", "driver", "doc",
    "dinosaur", "institute", and "frob".
    You can also have domain directories that don't have a corresponding
    group of wizards. The directory /d/std is an example.

    If a domain has files, but not wizards, it should be on the DOMAIN_DIRS
    #define but not on DOMAIN_LIST. If it has wizards but not files, then
    if needs to be on DOMAIN_LIST, not DOMAIN_DIRS. If it has both,
    then it needs to be on both #defines.


Sample Configuration
~~~~~~~~~~~~~~~~~~~~
Following is a sample configuration for installing a new domain called
`Northlands'.  Use this as a guide only...substitute your own names as
appropriate.  This section assumes you are already familiar LPC and that
you are an admin performing the configuration.

    Relevant Files:
        /include/domains.h
        /d/<domain_name>/adm/d_master.c
        /adm/etc/access
        /adm/etc/groups

    And suppose:
        Desired Ranks:
            player, wizard, elder, god

        Proposed Domain Lord:
            "Alpha"

        Other Wizards in the New Domain:
            "Beta", "Omega"

    [ ]  1. Add "northlands" to the DOMAIN_DIRS array in
            "/include/domains.h".

              #define DOMAIN_DIRS ({ "Fooland", "grid", "std", "northlands" })

            At this point, you can also change the levels (ranks) to
            something more to your liking.  Example:

              #define LEVEL_LIST ({ "player", "wizard", "elder", "god" })

            Note: There are #define's for ENTRY_LEVEL and MIN_SPONSOR_LEVEL.
                These represent the level wizards enter the domain (when
                first sponsored), and the minimum level of a wizard to
                sponsor another wizard to the same domain, respectively.
                A demotion from the ENTRY_LEVEL is removal from the domain.
                The default (and lowest) player level is 0.
                These are integer values that index into the LEVEL_LIST
                array, in the range from 0 to sizeof(LEVEL_LIST) - 1.  In
                this example we'll set them to:

              #define ENTRY_LEVEL 1         // "wizard"
              #define MIN_SPONSOR_LEVEL 3   // "god"

                At least a god (or admin), is needed to sponsor a player
                to the "northlands" domain.  Once sponsored, the player
                becomes a wizard.

    [ ]  2. Create the "northlands" domain subdirectory.

            mkdir /d/northlands
            mkdir /d/northlands/adm

    [ ]  3. Edit "/adm/etc/groups".  The first part is the `Northlands'
            domain group, while the second part is the domain name.

            (northlands)    Northlands

    [ ]  4. Edit "/adm/etc/access".  The first part is the `Northlands'
            domain directory path.  The second part consists of domain
            groups (in parentheses), followed by the permissions [in
            brackets--r = read access, w = write access].  Group/permission
            pairs are separated by a colon.

            (/d/northlands) (all)[r]:(northlands)[rw]:(admin)[rw]

    [ ]  5. Create the domain master file, "d_master.c" in the domain
            subdirectory.

            // File: /d/northlands/adm/d_master.c

            inherit "/adm/obj/master/d_master";

            create() {
                ::create();

                // create the group list
                //   lower case id of wizard followed by domain class
                group_list = ([
                    // Basic
                    getuid() : "objects",

                    // Domain Lord
                    "alpha" : "admin",

                    // Other Domain Wizards
                    "beta" : "northlands",
                    "omega" : "northlands"
                ]);

                // set the permissions
                //   domain class followed by a mapping specifying the
                //   permissions on subdirectories in the domain
                //   directory
                permission_list = ([
                    // Basic
                    "objects"     : ([ "/" : "r-", "data" :"rw"]),
                    "non-members" : ([ "/" : "r-" ]),

                    // "admin" domain class for the Domain Lord
                    "admin" : ([ "/" : "rw", "data" : "rw", "adm" : "rw"]),

                    // domain class for other wizards in the domain
                    "northlands" : ([ "/" : "rw" ])
                ]);
            }

         =======
            A note about permission_list:  The subdirectories are relative
            to the domain directory path.  "/" is the root domain directory,
            or "/d/northlands" in this case.  Similarly, "data" represents
            "/d/northlands/data" and "adm" corresponds to "/d/northlands/adm".

            The read/write permissions are not declared in the same manner
            as in "/adm/etc/access".  Here the only valid two character
            strings are: "--" (no access whatsoever), "r-" (read only),
            "-w" (write only), and "rw" (read and write access).
         =======

    [ ]  6. Shutdown and restart the mud, _OR_ update/reload the
            appropriate objects.

            update -R /adm/obj/master
            update /cmds/xtra/_sponsor
	    update /d/northlands/adm/d_master

    [ ]  7. Sponsor the intended domain lord (preferably to the highest
            domain rank).

            sponsor alpha Northlands    ; starts off as wizard in the domain
            sponsor alpha Northlands    ; promotion to elder
            sponsor alpha Northlands    ; promotion to god

    [ ]  8. At this point, the domain lord ("Alpha"), or yourself, can
            sponsor "Beta" and "Omega" to the `Northlands' domain.

            This concludes the tutorial.