Date sent:        	Wed, 16 Jul 1997 18:42:03 -0200
To:               "Liner/Nosferatu" <tgilly@teleport.com>
From:             Rick Rogers <frogers@engr.mun.ca> (by way of Rick Rogers <frogers@engr.mun.ca>)
Subject:          RCL: Part 2: Spec Structure/Virtual and Real Numbers/Start of
  the Spec File

Okay, here we go again.  In the first little bit of this
email, I'll continue to lay the fountation for making
a spec.  Then if I have the time, I might actually start
in on the most common specs we use.  Hold on, it gets
a little complicated.

Spec Structure
--------------

There are three types of specs - mob specs, item specs and
room specs.  Each has its own initial structure.  If you 
recall from last time, I said the room is sent a command,
then the character/mob and then the items.  Well these
commands are sent to the specs using the following forms.

int room_spec_name(int room,CHAR *ch, int cmd, char *arg)
int mob_spec_name(CHAR *mob,CHAR *ch, int cmd, char *arg)
int item_spec_name(OBJ *obj,CHAR *ch, int cmd, char *arg)

Lets look at these things in detail.

First of all the int at the front of each one.  Basically
when a spec ends it must return either TRUE or FALSE.  This
TRUE or FALSE is passed to the procedure used to signal the
room/mob/item.  There is only one thing to remember.  If you
want the code to stop processing the command, return TRUE,
otherwise return FALSE.

Next we have either room, *mob or *obj.  This is simply the
real number of the room, a pointer to the mob that owns the
spec or a pointer to the item that owns the spec.  For those
of you curious, CHAR is shorthand for struct char_data and
OBJ is shorthand for struct obj_data.

Next and common to all three is the *ch.  This is a pointer to
the character that typed the command.  This is 0 if the command
was one of the muds automatic signals.  Then its cmd, that is
the command number.  Finally we have *arg.  This is a character
field for the arguments of the command.

I'm sure many are confused, so an example is in order.

Lets say at the QA, Wulf types "disembowel ant".
If the QA had a spec, when it got called....

*mob = pointer to queen ant
*ch  = pointer to wulf
cmd  = CMD_DISEMBOWEL
*arg = "ant"

another example the code sends out MSG_TICK to the QA spec

*mob = pointer to queen ant
*ch  = 0
cmd  = MSG_TICK
*arg = ""

Hopefully this is understood, if not bug me about it.


Virtual and Real Numbers
------------------------

Above I mentioned the real room number for room specs.
For those of you who have used our olc system, you know
the virtual number is the number of your mob/room/object
in the world files.  However, this is basically useless
from a code point of view since the virtual numbers follow
no particular order.  Also, with multiple items of the
same virtual number, something is need to tell the difference
between them.  This is where real numbers come in.  Whenever
a room/mob/object is loaded it is assigned the next real number
available.

All you have to remember is that if you want to check the
virtual number of a mob, room or object, you need to call
a special procedure to get that number.

Start of the Spec File
----------------------

Okay enough foundation, the rest your going to have to learn
from example.  First you think of a name for your spec
file.  We use a simple naming convention like spec.dasharr.c
or spec.abyss.c, or even spec.pagoda.c - get the point yet?

Now the start of your spec is usually a comment of the following
form.

/*   spec.xxxxx.c - Specs for <Insert area name here.>

     Written by <Your name here> for RoninMUD
     Last Modification Date:

     Any comments you want to add.
*/

Now the include files.  These are impt as these have info
about what the commands are (cmd.h) what all the main
structures mean (structs.h), what the utility subroutines
are (utility.h utils.h) etc.

#include <stdio.h>
#include <string.h>
#include <ctype.h>
#include <stdlib.h>
#include <unistd.h>

#include "structs.h"
#include "utils.h"
#include "comm.h"
#include "interpreter.h"
#include "handler.h"
#include "db.h"
#include "spells.h"
#include "limits.h"
#include "cmd.h"
#include "utility.h"
#include "act.h"
#include "fight.h"
#include "spec_assign.h"
#include "mob.spells.h"
extern struct time_info_data time_info;

Now we can start with the main code.  To make things
nice and easy to read, we usually use definitions for
mob/room/object numbers in the specs instead of the
actual numbers themselves.  For example...

#define QUEEN_ANT    12001
#define GOLDEN_BELT  12021
#define ANT_ROOM     12063

So whenever we needed to use the virtual number of the
above, we'd use the definition instead.  We mainly do
this when assigning the specs to the room/mob/item.  We do
this using the following procedure.

void assign_xxxxx(void) {
  assign_mob(QUEEN_ANT , queen_ant_spec);
  assign_room(ANT_ROOM , ant_room_spec);
  assign_obj(GOLDEN_BELT, golden_belt_spec);
)

The assign_xxxxx function is called from the main code.

So thats the initial basics every spec needs. Next time,
we'll start looking at example specs and then you'll
really start to understand my rantings.

Rick (Ranger)