::: Room function documentation :::

Comments:
     Rooms are possibly the most important part of the mud. It sets the scene
     for players, and makes things more realistic. There are thus some ways
     that rooms should be coded, and some things that Creators should not code.

SEE ALSO: 'man qc' for further documentation


FUNCTIONS

1) Exits

varargs string *query_door_exits(int arg);
Comment: arg
          0  returns an array of door exits (same format as exit array).
          1  returns an array of open exits
          2  returns an array of closed exits
          3  returns an array of secret doors

string *query_all_exits();
Comment: returns an array of all exits + door exits

string *query_open_exits();
Comment: returns an array of all exits + open door exits.

string *query_closed_exits();
Comment: returns an array of all closed exits



2) Set Functions

string set_day_desc(string str);
Comment: tagged onto end of long when daytime.

string set_night_desc(string str);
Comment: tagged onto end of long when nighttime.

void   set_exits(string *arr);
Comments: this is an array with the form, ({destination filename,
direction,}).

E.g. set_exits(({ "room/shop", "west", "room/city/square", "square", }));

void   set_extra_objects(string *arr);
Comment: this is an array of ids, filenames that are cloned and moved to the
player with get, or take. There is an infinite supply of these extra objects.
A number of different ids can be separated by a "#".

E.g. set_extra_objects(({ "knife#dagger", "players/zilanthius/knife", }));


void   set_items(string *arr);
Comment: These are items that can be looked at. The array format is ids,
description.  

Eg. set_items(({ "desk#table", "The table is made of mahogony.\n", }));


void   set_night_items(string *arr);
Comment: This is the same as set_items() except these can only be looked at
during the night.

void   set_day_items(string *arr);
Comment: This is the same as set_items() except these can only be looked at
during the day.
  


int    set_climb(int i);
int    set_fall_dam(int i);
Comment:  when a player does an up, or down move. set climb value is compared
against the players climb stat. If the player fails they fall. They take fall
damage set by set_fall_dam().


void   set_doors(mixed *arr);
Comment: Use load door its a little more user friemdly.

varargs void set_sign_message(string sign_msg, string sign_lang);
Comment: this clones a sign object to the room. I think this isn't set up
properly?? Zil.

string *set_search_array(string *arr) { return search_array = arr; }
int set_search_complex(int i)      { return search_complex = i; }
Comment: similar to item list. Has a format id, search description. A search
compares the search complexity to the players intelligence.

E.g. set_search_array(({ "desk", "You find a scratch.\n", }));



set_weather(int light, int weather, int climate);
Comment: Day and night are an integral part of the mudlib's rooms. 
     int light - this value is decreased by 1 during the night. If 
                 there is an artificial light source present during the 
                 night (see set_night_desc/set_night_items etc) then the 
                 light should be set to 2. Magical light is about 3 to 5,
                 magical darkness is -1 to -3. Normal darkness is 0.

                 If a room is always to be dark (because it is in a cave)
                 then set the light value to 0. At night this will drop
                 1 light point to -1.

                 Note also that each torch is equal to +1 light point.
               

     int weather -  0 DEFAULT WEATHER MESSAGES
                    1 NO WEATHER MESSAGES
                    2 INSIDE MESSAGES
                    3 SHELTER MESSAGES
                    4 FULL WEATHER

     int climate -  0 NORMAL
                    1 BAD WEATHER
                    2 TROPICAL WEATHER
                    3 JUNGLE WEATHER
                    4 DESERT WEATHER
                    5 ARCTIC WEATHER
                    6 SEA WEATHER

     Each weather message is dependant upon day/night, and climate allowed
for that room, and finally the weather type. 


3) Query Functions

string query_day_desc();
string query_night_desc();
string *query_dest_dir();
string *query_extra_objects();
string *query_items();
string *query_night_items();
string *query_day_items();

string query_sign_message();
string query_sign_language();


string query_exit_filename(string str);
Comment: returns the filename for a given direction.


string query_file_exitname(string file);
Comment: returns the exit direction for a given filename.


mixed  *query_doors();
Comment: returns the full door array. Look at door_mac.h for an interpretation
of the door array.


4) Movement in Rooms

void   exits(status brief);
Comment: writes out the exits to a room. Including doors.

status ready_to_move(string str);
Comment: the direction taken is given by the action verb. However, to enable
two word directions, the argument str. Thus,
set_exits(({ "room/shop", "north shop", })); is now a legitemate direction.

void   move(string str);
Comment: Unlike the old way of giving just a direction. str is of the format
"direction#filename".

 
5) Dynamic Exits

status add_exit(string where, string direction);
status remove_exit(string dest);
status change_exit_room(string old_dest,string new_dest);
Comment: These allow you to add and remove exits.


6) Extra Objects

status add_extra_object(string id_extra_object, string file_extra_object);
status remove_extra_object(string id_extra_object);
status get_extra_object(string id_extra_object);
Comment: More stuff for extra objects.


7) Doors  

varargs status add_door(string dir,
                       string dest,
                status closed_flag,
                  string door_desc, 
                          int lock,
                     string key_id,
                      int trap_dam,
                   status trap_set,
                   int secret_door);
Comment: add a door. the function load_door() is more user friendly.


void load_door(mixed *arg);
Comment: 

Eg.
load_door(({ 
     "destination",     filename,
     "direction",       direction,
     "closed", /* or "open" */
     "description",     door_description,
     "lock difficulty", difficulty,  /* compare to thief's query_locks() */
     "key",             key_id,      /* keys id                          */
     "trap damage",     damage,      /* damage cause by a trap           */
     "secret door",     find_difficulty, /* compared to intelligence     */
     "door number",     door_number,     /* multiple doors to the same room
                                          require a matching door number */
}));


status remove_door(string str);
Comment: remove a door exit.

status door_to_move(string str);
status open(string str);
status close(string str);
status disarm_door_trap(string str);
varargs status set_door_trap(string dest_filename,status on,string door_id);
varargs status set_door_closed(string dest_filename,status close,string id);
void reset_doors(status arg);
Comment: miscelaneous door functions. You don't need to know these.

string search_room(string id);
Comment: If id is "room" does a secret door search. Search search array for
'id'. If it doesn't find it in the array string it will search for an object
in the room, or on the player and call the function search_ob(id). Make sure
the function returns 1. 

string set_enter_msg(string s) { return enter_msg = s; }
string set_exit_msg(string s)  { return exit_msg = s;  }
string query_enter_msg()       { return enter_msg;     }
string query_exit_msg()        { return exit_msg;      }