Magma MUD version 3.04

https://github.com/Xangis/magma

=== Note

Some of the stock Envy and UltraEnvy areas no longer work with this
codebase and should not be used.  Areas should be written with some
version of DikuEdit, preferably version 3.00c.  The MZF (MakeZonesFast)
application should also be able to create Envy-format areas that will
be loadable by the MUD.


=== Preface

This document was originally from the UltraEnvy 0.87j code release by Zen.
Most of it has been left intact, and only the portions that have changed
have been modified.

                                        - Xangis

Portions of this document contains certain clarifications and
modifications sent in by hub@hub.eden.com.  Otherwise, the original
document is intact.

					- Kahn

The majority of this document was submitted to the merc mailing list by RoX of
Farside, and we are greatly indebted to the Farside staff for this excellent
introduction to area building.  We have modified the text slightly to 
match the changes made at EnvyMud (especially the removal of slot numbers),
removed references to Farside immortals (You may still ask them them what to
do! :) ), and have added our own examples, but have otherwise left the
original document intact.
					- Thelonius



=== Acknowledgment (from Silence of Farside) 

This document contains information from 'database.doc', 'dbsup.doc', and
'values.doc', part of the original Diku mud release and copyrighted by the
Diku folks.  See their 'license.doc'.

I have made this file from building.txt and the other area building files
included in the Merc22 package then expanded and edited them to make it
easier for first area writers.  All thanks go out to the creators of mud.

Some starting hints

Plan out your area on paper before writing it out.  Check the mud to see if
that area is already in place or something similar.  Map out your area, then
place the mobs and items BEFORE you start writing the area.  Think before you
write.  Read through this document, and try and figure it out.  If you still
need help, don't hesitate to ask someone online.  Try to have as close to, but
less than, sets of 100 rooms as you can, since we use 100 roomed slots.  Let 
your imagination run wild and remember to place exits in the long description, 
including doors.  While writing your area, have a previously written and 
debugged area nearby so you can use it as a reference.



=== Overview of Areas:

An area is one piece of the world.  Each area is defined in a separate file.
All of our area files have the extension '.are'.  Areas are what make the
game special, sure the gods help, but it is the areas.  Please keep your
areas original and not too far out.  Use good and proper English and try and
spell check your area before sending it in.  Hatchet and the high up gods will
debug if necessary.  Remember the world is a magical one, where technology
was not really developed.  So please keep the machine guns, grenades, lasers,
etc out.

EnvyMud has changed the format of the value# fields of the objects in the
area files.  Mainly the removal of slot number references in potions, wands,
staves, etc.  But, since each area file is a separate file, it is still easy
to port areas from one diku mud to another through a simple conversion.

EnvyMud 2.2 has added race definitions for mobiles taking the place of the
former repop position.  IE) sleeping or etc.  See the #MOBILES section below
for a more indepth description.

All of our areas may be freely distributed, as long as the internal notices
(such as those on plaques, signs, graffiti, or tombstones) are kept.  If you
write new areas, and would like to contribute them back to EnvyMud, just
e-mail to one of the addresses above.  As you can see from typing 'areas' in
the game, we credit the original authors whenever we can find them.

Although the format of EnvyMud areas is (somewhat) compatible with other Diku
and MERC muds, EnvyMud ignores many of the fields in the area files,
generating its own values based on mobile and object levels.  We adopted this
policy in order to maintain balance between areas originally written by many
different authors.



=== New area format and OLC info

This file may be incomplete but at least you have a reference to work on.
The server can still load old UltraEnvy areas and then you can do an
'asave world' to save the entire database in the new format.  This file format
is picky on the #RESETS section.  You may need to erase one or two lines but
it will warn of that in the log file. 

The new area format is a work in progress, so it may change and i'm not certain
i'll bother doing a converter from my older area file formats.

If you want to do area editing using OLC, remember you need authorization to do
it.  This means one of two things:

1)  Your 'security' field (saved in the 'Security' line on the pfile) is higher
      than the security level of the given area (use 'alist' to see this).
2)  Your name is in the 'Builders' line on the area file's #AREADATA section.


					- Zen

* NOTE *
OLC has not currently been setup to save areas in the new format.  If you
save the world, areas may become corrupted and the whole MUD may become worthless.


=== How to convert the standard Envy2.2 areas

If 'asaving' the Envy2.2 release areas swap the order of haon.are and
arachnos.are in the AREA.LST file so that the resets will load correctly.
The order in your AREA.LST file should now be:

   arachnos.are
   haon.are

Put naytil.are before grove.are like so:

   naytil.are
   grove.are

Put shaolin.are before ocean.are like so:

   shaolin.are
   ocean.are

Now the old areas should be properly converted.



=== Sections of an Area

An area file contains the following sections:

    #AREADATA			(unchanged)
    #HELPS			(unchanged)
    #RECALL			(unchanged/unused)
    #BASTMOBS			(changed alot)
    #BASTOBJECTS		(changed alot)
    #BASTROOMS			(changed moderately)
    #BASTRESETS			(changed moderately)
    #BASTSHOPS			(changed alot)
    #SPECIALS			(unchanged)
    #GAMES			(unchanged)
    #$

An area is a collection of sections starting with #AREADATA until the next
#AREADATA.  All of our area files (except 'help.are') contain just one
#AREADATA section, which is at the top of the file.

The file 'proto.are' contains a prototype for developing new area files.

=== Data Types (the following was taken straight out of builders.txt)

All of the data in an area file (even the section headers) consists of a
series of values.  Each value has a specific type.  The server parses the
file by reading in data values one at a time according to the types it
expects.

Blank characters (spaces, tabs, new lines, carriage returns) at the beginning
of a data value are always ignored (this includes strings).  Thus, you can
format the area files whatever way suits your taste and your needs.

The individual types are: 'letter', 'word', 'string', 'number', and 'to_eol'.

A 'letter' is a single non-blank character.

A 'word' is a sequence of non-blank characters terminated by a blank.

A 'string' is a sequence of non-tilde characters terminated by a tilde.  A
tilde is this character: '~'.  Thus, strings may contain blanks, and may be
multiple lines long.  There is no limit on the length of an individual
string; however, all strings go into a common memory pool whose size is fixed
when the server is compiled.

A 'number' is a decimal number with an optional leading '-' or '+'.  The '|'
character may be used in any number: '1|64|1048576' has the value 1048641. 
The individual values separated by '|' are added together, so '5|6' is 11,
not 7. The components need not be powers of 2.  This feature is extremely
useful for defining bit vectors, such as the ACT_* and AFF_* bits for
mobiles, but is not restricted to bit vectors: any number may use the '|'
construction. ie, when putting affects together, all you need to do is the
following (example is a mob who is aggressive and stays in one room) 1|2|32.

A 'to_eol' is all the characters from the current position to the end of the
current input line.  It is used for parsing comments at the ends of lines.

In the syntax description below, <value:type> indicates a value to be read of
the indicated type.  A backslash '\' indicates that the file format itself
has only one line, but several lines are used in this description to fit
within 80 columns.

Braces '{ ... }' are used to enclose elements.  They are NOT literal parts of
the file format, but a way of indicating that the enclosed elements may be
repeated zero or more times.  Braces at the same level of indentation
indicate that the parallel elements may be present in any order.

All other characters in the syntax description are literal characters.

Mobiles, objects, and rooms are identified by vnum (virtual number).  The
range of vnum's is 1 to 65534.  Vnum's must be unique (for that particular
kind of vnum).  Vnums do not have to be in increasing order.

Typically an area uses the same range of vnum's for mobile vnum's, object
vnum's, and room vnum's, starting with a multiple of 100.  This facilitates
adding the area into an existing set of areas.

At EnvyMud, we do not preassign room vnum's.  Instead, all of your vnums
should be of the form XX01, or **01, or any other easily replaced string.
They will be changed when we incorporate your area into the mud.



== The #AREADATA section (from this point onwards, I have changed things around)

The syntax of this section is:

    #AREADATA
    Name      <area-name:string>
    Author    <author-name:string>
    Levels    <lower:number> <higher:number>
    Security  <security:number>
    Builders  <builders:string>
    VNUMs     <start:number> <end:number>
    Recall    <recall-point:number>
    Reset     <reset-message:string>
    End

The 'area-name' can be any string.  Example for an #AREADATA section:

    #AREADATA
    Name        Prototype for New Area~
    Author      Envy~
    Levels      5 35
    Security    1
    VNUMs       3000 3383
    Builders    None~
    Recall      3001
    Reset       You hear the patter of little feet.~
    End

The two numbers in 'Levels' are recommended level range.  The 'Author' is the
name of the original author of the area.  The 'Name' is the name of the area.

The 'recall-point' gives the vnum of the room to which a player will 
recall if they attempt to do so anywhere within the area defined in the
current file.  If this section is omitted, the recall point will be the
standard ROOM_VNUM_TEMPLE as defined in merc.h.  It is distributed as room
vnum 3001 in midgaard.are.  If the 'recall-point' is invalid, the player
is unable to recall when attempted in the zone.  This function was added by
Kahn to allow for builder-settable recall points.  If ommited, 'reset-message'
will be 'You hear the patter of little feet.'


=== The #HELPS section

This section is usually omitted from area files but may be included to
better enhance your area.  For instance, your zone containing many
dwarves might have a HELP DWARF section.  This individual help gets tacked
onto the pool of all helps.  Conflicting helps are resolved by EnvyMud by
displaying all instances of the help.

Generally, all helps are placed in one file, help.are, that contains no
other sections.  The syntax of a help entry is as follows:

    #HELPS
    {
	<level:number> <keywords:string>~
	<help-text:string>~
    }
    {
	<level:number> <keywords:string>~
	<help-text:string>~
    }
    0 $~

The 'level' number is the minimum level necessary to read the help for the
given topic.  For example:

50 IMMTALK :~

would mean that only players of level 50 or higher could read the helps
for the 'immtalk' command.

The 'keywords' are the text strings that must be matched in order to see
this particular help entry.  Case is unimportant, though typically the
keywords are capitalized.  For two-word entries, single quotes must be
placed around each phrase.  For example:

0 'CURE POISON'~

The 'help-text' of the help is completely at the discretion of the builder.
Spells usually give a syntax example, followed by a summary:

0 'CURE POISON'~
Syntax: cast 'cure poison' <victim>

This spell will remove the effects of poison from the victim's body.
~

Normally when a player uses 'help', both the keywords and the help-text are
shown.  If the 'level' is negative, however, the keywords are suppressed.  This
allows the help file mechanism to be used for certain other commands, such as
the initial 'greetings' text.

If a 'help-text' begins with a leading '.', the leading '.' is stripped off.
This provides for an escape mechanism from the usual leading-blank stripping of
strings, so that picturesque greeting screens may be used.

0 $~:  This goes to the end of the entire #HELPS section to notify the
area loader that the #HELPS section is over.



=== The #BASTMOBS section

These are the mobs in your neighborhood, in your neighborhood.. oh sorry
just passed through Lenny's area.  Anyways, it is here that a lot of the
character of your area comes out.  This is the most important section to
those players who walk around with brief on.
The syntax of this section is:

    #BASTMOBS
    {
     #<vnum:number>
     <keywords:string>
     <short-description:string>
     <long-description:string>
     <description:string>
     <act-flags:number> <aff1:number> <aff2:number> <aff3:number> <aff4:number> <alignment:number> S          
     <two-letter race key:string> <unused:number> <class:number>
     <level:number> <hitroll:number> <armor:number>			\
     <hitnodice:number> d <hitsizedice:number> + <hitplus:number>	\
     <damnodice:number> d <damsizedice:number> + <damroll:number>
     <gold:string> <exp:number>
     <position:number> <default position-unused:number> <sex:number>
    }
    #0

The 'vnum' is the virtual number of the mobile.  IE) #654

The 'keywords' are words which can be used in commands to identify the
mobile.  Most mudders consider the keywords the mobile's name.
Separate each keyword you use with a space and make sure at least one
of them occurs in the description the player sees when they enter the
room for ease of reference if you intention is to have a visible mobile.

The 'short-description' is the description used by the 'act' function and
other functions to identify the mobile.  Do not use a capital letter
in the description as it is used from within sentences.

The 'long-description' is the description used when a character walks in the
room and the mobile is visible.  It is suggested to not use more than
one line for the 'long-description'.  Make sure you end the
description with a newline with a '~' only.  (example:

	An old woman totters down the street~

is incorrect.

An old woman totters down the street.
~

is correct.)

The 'description' is the longest description.  It is used when a character
explicitly looks at the mobile.  This may contain as many lines as you
wish.  This can even include a fake listing of what it is wearing.
 
The 'act-flags' define how the mobile acts.  See merc.h for a full list of
the act flags.
ACT_ flags:
  IS_NPC           1         Auto set for mobs
  SENTINEL         2         Stays in one room
  SCAVENGER        4         Picks up objects 
  AGGRESSIVE      32         Attacks PC's     
  STAY_AREA       64         Won't leave area 
  WIMPY          128         Flees when hurt  
  PET            256         Auto set for pets
  TRAIN          512         Can train PC's   
  PRACTICE      1024         Can practice PC's
  MOUNTABLE   131072         Can be mounted (ridable)


The 'affected-flags' define more attributes of the mobile.  See merc.h and
bit.c for a full list of the affected flags.
AFF_ flags:
  BLIND                  1
  INVISIBLE              2
  DETECT_EVIL            4
  DETECT_INVIS           8
  DETECT_MAGIC          16
  DETECT_HIDDEN         32
  HOLD                  64       
  SANCTUARY            128
  FAERIE_FIRE          256
  INFRARED             512
  CURSE               1024
  POISON              4096
  PROTECT_EVIL        8192
  SNEAK              32768
  HIDE               65536
  SLEEP             131072
  CHARM             262144
  FLYING            524288
  PASS_DOOR        1048576
  WATERWALK        2097152       
  SUMMONED         4194304       (Soon to be implemented) 
  MUTE             8388608     
  GILLS           16777216       
  VAMP_BITE       33554432	     (internally set)
  GHOUL	          67108864	     (internally set)
  FLAMING        134217728
  DETECT_GOOD    268435456
  PROTECT_GOOD   536870912
  PLAGUE        1073741824

The 'alignment' of the mobile ranges from -1000 to +1000.  Keep in mind that
certain spells ('protection' and 'dispel evil') give characters fighting evil
monsters an advantage, and that experience earned is influenced by alignment.

The literal letter 'S' must be present after the alignment.  In the original
Diku mob format, 'S' stands for simple.  Envy supports only simple mobs, so
the 'S' is redundant.  It is retained not only for compatibility with the
Diku format, but also because it helps the server report errors more
accurately.

The 'level' is a number from 1 to 50.

The 'hitroll', 'armor', 'hitnodice', 'hitsizeddice', 'hitplus', 'damnnodice',
'damsizedice', 'damroll', 'gold', 'exp', and 'position' fields are
present for compatibility with original Diku mud, but their values are ignored.
Envy generates these values internally based on the level of the mobile.

Race name consists of one of these many races built into EnvyMud 2.2.  This
list may change when you add more races into the mud.

    Human, Elf, Halfelf, Drow, Dwarf, Halfdwarf, Hobbit, Giant, Ogre, Orc,
    Kobold, Minotaur, Troll, Hobgoblin, Insect, Dragon, Animal, God, Undead,
    Harpy, Bear, Githyanki, Elemental, Bat, Plant, Rat, Vampire, Werewolf,
    Goblin, Faerie, Arachnid, Mindflayer, Object, Mist, Snake, Worm, Fish,
    Hydra, Lizard, Gnome, Halfkobold

Sex:
  NEUTRAL           0
  MALE              1
  FEMALE            2

As an example, I will use a mob that is in the githzerai castle.

#15012
githzerai trainee~
A githzerai trainee~
A githzerai is here training in the art of death.
~
This githzerai is covered in scratches.  He obviously doesn't want to end up
like the blood stains on the ground.  He stands on guard waiting for you to
make your first move.
~
67 548 0 0 0 -1000 S
GI 0 0
41 0 1 0d0+0 0d0+0
0.0.0.0 0
8 8 1


=== The #BASTOBJECTS section

These are the items that the people who journey through you area will keep
and use, it is best to think up good descriptions for them.  Remember to
balance these items with those that already exist.
The syntax of this section is:

    #NEWOBJECTS
    {
     #<vnum:number>
     <keywords:string>~
     <short-description:string>~
     <long-description:string>~
     <action-description:string>~
     <item-type:number> <extra-flags:number> <wear-flags:number>     
     <val0:string>~ <val1:string>~ <val2:string>~ <val3:string>~ <val4:string>~
     <weight:number> <cost:number> <cost-per-day:number>
     {
         E
         <keyword:string>
         <description:string>
     }
     {
         A
         <apply-type:number> <apply-value:number> <apply-bitvector:number>
     }
    }
    #0


The 'vnum' is the virtual number of the object.

The 'keywords' are words which can be used in commands to identify the
object.

The 'short-description' is the description used by the 'act' function and
other functions to identify the object.  The first character of the short-
description should be lower case, because this description is used in the
middle of sentences.  The 'short-description' is used with the
commands: 'get', 'drop', 'inventory', 'equipment', 'look', etc.

The 'long-description' is the description used when a character walks in the
room and the object is visible.  This string will display when someone
types 'look <obj>'.

The 'action-description' is not used, which why you just put a ~ there.

The 'item-type' is the type of the item.

ITEM_ types:
  LIGHT       1
  SCROLL      2
  WAND        3
  STAFF       4
  WEAPON      5
  TREASURE    8
  ARMOR       9
  POTION     10
  FURNITURE  12
  TRASH      13
  CONTAINER  15
  DRINK_CON  17
  KEY        18
  FOOD       19
  MONEY      20
  BOAT       22
  CORPSE_NPC 23
  CORPSE_PC  24
  FOUNTAIN   25
  PILL       26
  PORTAL     28
  WARP_STONE 29
  CLOTHING   30
  RANGED_WPN 31
  AMMO       32

The 'extra-flags' describe more attributes of the object.  The 'wear-flags'
describe whether the item can be picked up, and if so, what bodily locations
can wear it.

Extra ITEM_ flags:
  GLOW         		   1
  HUM          		   2
  DARK         		   4
  LOCK         		   8
  EVIL         		  16
  INVIS        		  32
  MAGIC        		  64
  NODROP       		 128
  HOLY        		 256
  ANTI_GOOD    		 512
  ANTI_EVIL    		1024
  ANTI_NEUTRAL 		2048
  NOREMOVE     		4096
  INVENTORY    		8192
  POISONED    	       16384
  VAMPIRE_BANE         32768
  VISIBLE_DEATH       131072

WEAR_ flags:
  TAKE            1
  WEAR_FINGER     2
  WEAR_NECK       4
  WEAR_BODY       8
  WEAR_HEAD      16
  WEAR_LEGS      32
  WEAR_FEET      64
  WEAR_HANDS    128 
  WEAR_ARMS     256
  WEAR_SHIELD   512
  WEAR_ABOUT   1024 
  WEAR_WAIST   2048
  WEAR_WRIST   4096
  WIELD        8192
  HOLD        16384

The interpretation of the four 'values' depends upon the type of the object. 
These values are entered as strings and MUST be terminated by a tilde (~), but
will be changed to integers depending on the type of the object and the form
of the input.  Interpretations are given below.

The 'weight' of the object is just that.

'Cost' and 'cost-per-day' are ignored.  'Cost' is generated internally based
on the level of the object.  Because Envy has no rent, 'cost-per-day' is
completely ignored.

The optional 'E' sections and 'A' sections come after the main data.  An 'E'
section ('extra description') contains a keyword-list and a string associated
with those keywords.  This description string is used when a character looks
at a word on the keyword list, ie) a gem on a scepter would be:

E
gem~
A small glowing red gem pulsates silently on the tip of the scepter.
~

This allows for an added dimension in your objects.  I suggest you put extra
descriptions on your important objects that have items of note on them.
It might even be desirable to link your extra descriptions to give just so
much information at a time, leading each extra description to each other.

An 'A' section ('apply') contains an apply-type, an apply-value and an bitvector.
When a character uses this object as equipment (holds, wields, or wears it),
then the value of 'apply-value' is added to the character attribute identified
by 'apply-type'. The 'apply-bitvector' is added to the attribute of the
character.

APPLY_ types:
  NONE           0
  STR            1
  DEX            2
  INT            3
  WIS            4
  CON            5
  SEX            6
  CLASS          7
  LEVEL          8
  AGE            9
  HEIGHT        10
  WEIGHT        11
  MANA          12
  HIT           13
  MOVE          14
  GOLD          15
  EXP           16
  AC            17
  HITROLL       18
  DAMROLL       19
  SAVING_PARA   20
  SAVING_ROD    21
  SAVING_PETRI  22
  SAVING_BREATH 23
  SAVING_SPELL  24

The 'apply-bitvector' defines the altered attributes of the character.
AFF_ flags:
  BLIND                  1
  INVISIBLE              2
  DETECT_EVIL            4
  DETECT_INVIS           8
  DETECT_MAGIC          16
  DETECT_HIDDEN         32
  HOLD                  64       
  SANCTUARY            128
  FAERIE_FIRE          256
  INFRARED             512
  CURSE               1024
  POISON              4096
  PROTECT_EVIL        8192
  SNEAK              32768
  HIDE               65536
  SLEEP             131072
  CHARM             262144
  FLYING            524288
  PASS_DOOR        1048576
  WATERWALK        2097152       
  SUMMONED         4194304       (Soon to be implemented) 
  MUTE             8388608     
  GILLS           16777216       
  VAMP_BITE       33554432	     (internally set)
  GHOUL	          67108864	     (internally set)
  FLAMING        134217728
  DETECT_GOOD    268435456
  PROTECT_GOOD   536870912
  PLAGUE        1073741824

An object may have an unlimited number of 'E' and 'A' sections.


--- Meaning of Value Numbers by Item Type

As mentioned above, the 'value' fields are entered by the builder as TEXT 
strings even though they will be converted to and stored as integer values.
EnvyMud made this modification so that spell names, rather than slot numbers,
could be used for scrolls, staves, wands, potions, and pills.  For these types
of items, the text string containing the spell name (for example, cure
critical) is translated to an internal skill/spell number or 'sn'.  For the
other item types, the strings are converted directly to integer values.  If a
potion, scroll, or pill only has one spell, the other strings must still be
terminated by a '~' but need not have any content.  A complete list of spells
is given at the end of this file.

NOTE:  Because these are read in as strings, the '|' format cannot be used for
the flags; i.e. 1|4|8~ is an invalid entry, but 13~ is valid. (cf.
ITEM_CONTAINER, value[1])

01 ITEM_LIGHT
   value[0]    unused
   value[1]    unused
   value[2]    hours of light available, 0 is dead, -1 is infinite            
   value[3]    unused
   value[4]    unused

02 ITEM_SCROLL
   value[0]    level
   value[1]    spell name 1
   value[2]    spell name 2
   value[3]    spell name 3
   value[4]    spell name 4

03 ITEM_WAND
   value[0]    level
   value[1]    max charges
   value[2]    current charges
   value[3]    spell name
   value[4]    unused

04 ITEM_STAFF
   value[0]    level
   value[1]    max charges
   value[2]    current charges
   value[3]    spell name
   value[4]    unused

05 ITEM_WEAPON
   value[0]    unused
   value[1]    unused (formerly min damage)
   value[2]    unused (formerly max damage)
   value[3]    weapon type:
      00     hit
      01     slice
      02     stab
      03     slash
      04     whip
      05     claw
      06     blast
      07     pound
      08     crush
      09     grep
      10     bite
      11     pierce
      12     suction
      13     chop
      14     vorpal
      15     cleave
      16     wail
   value[4]    unused

08 ITEM_TREASURE
   value[0]    unused
   value[1]    unused
   value[2]    unused
   value[3]    unused
   value[4]    unused

09 ITEM_ARMOR
   value[0]    unused 
   value[1]    unused
   value[2]    unused
   value[3]    unused
   value[4]    unused

10 ITEM_POTION
   value[0]    level
   value[1]    spell name 1
   value[2]    spell name 2
   value[3]    spell name 3
   value[4]    spell name 4

12 ITEM_FURNITURE
   value[0]    unused
   value[1]    unused
   value[2]    unused
   value[3]    unused
   value[4]    unused

13 ITEM_TRASH
   value[0]    unused
   value[1]    unused
   value[2]    unused
   value[3]    unused
   value[4]    unused

15 ITEM_CONTAINER
   value[0]    weight capacity
   value[1]    flags: 1 closeable, 2 pickproof, 4 closed, 8 locked
   value[2]    key vnum
   value[3]    unused
   value[4]    unused

17 ITEM_DRINK_CON
   value[0]    capacity
   value[1]    current quantity
   value[2]    liquid number (see 'liq_table' in const.c)
   value[3]    if non-zero, drink is poisoned
   value[4]    unused

18 ITEM_KEY
   value[0]    unused (often vnum of room/container it unlocks)
   value[1]    unused
   value[2]    unused
   value[3]    unused
   value[4]    unused

19 ITEM_FOOD
   value[0]    hours of food value
   value[1]    unused
   value[2]    unused
   value[3]    if non-zero, food is poisoned
   value[4]    unused

20 ITEM_MONEY
   value[0]    value in gold pieces
   value[1]    unused
   value[2]    unused
   value[3]    unused
   value[4]    unused

22 ITEM_BOAT
   value[0]    unused
   value[1]    unused
   value[2]    unused
   value[3]    unused
   value[4]    unused

23 ITEM_CORPSE_NPC
   value[0]    unused
   value[1]    unused
   value[2]    unused
   value[3]    unused
   value[4]    unused

24 ITEM_CORPSE_PC
   value[0]    unused
   value[1]    unused
   value[2]    unused
   value[3]    unused
   value[4]    unused


25 ITEM_FOUNTAIN
   value[0]    unused
   value[1]    unused
   value[2]    unused
   value[3]    unused
   value[4]    unused

26 ITEM_PILL
   value[0]    level
   value[1]    spell name 1
   value[2]    spell name 2
   value[3]    spell name 3
   value[4]    spell name 3

28 ITEM_PORTAL
   value[0]    current charges
   value[1]    flags: 1 closeable, 2 pickproof, 4 closed, 8 locked
   value[2]    key vnum
   value[3]    flags: 1 nocursed, 2 gowith, 4 random, 8 buggy
   value[4]    destination vnum

29 ITEM_WARP_STONE
   value[0]    unused
   value[1]    unused
   value[2]    unused
   value[3]    unused
   value[4]    unused

30 ITEM_CLOTHING
   value[0]    unused
   value[1]    unused
   value[2]    unused
   value[3]    unused
   value[4]    unused

31 ITEM_RANGED_WEAPON
   value[0]    ammo vnum
   value[1]    unused (formerly min damage)
   value[2]    unused (formerly max damage)
   value[3]    ranged weapon type:
      00     bow
      01     crossbow
      02     catapult
   value[4]    unused

32 ITEM_AMMO
   value[0]    ammo type:
      00     bow
      01     crossbow
      02     catapult
   value[1]    add to damage
   value[2]    unused
   value[3]    unused
   value[4]    unused

Examples:
ITEM_ARMOR:
0~ 0~ 0~ 0~ 0~
(all values are set internally)

ITEM_WEAPON:
0~ 0~ 0~ 11~ 0~
(damage range value[1]-value[2] is set internally; this is a piercing weapon)

ITEM_POTION:
25~ teleport~ cure critical~ ~ ~
(note that only two spells are used; the third is left blank)

ITEM_PORTAL:
12~ 1~ 0~ 0~ 3001~
Portal with 12 charges (can transport 12 people), closeable, when you enter
the portal you go to vnum 3001 (Temple of Midgaard)

ITEM_STAFF:
15~ 3~ 3~ ultrablast~ 0~

And a complete item from the githzerai castle:
#15010
black control staff~
Black staff of control~
A black staff that is neither wood or rock stands here.
~
~
4 64 16385
47~ 25~ 25~ charm person~ 0~
2 0 0
A
24 -5

Remember, you can use previously defined items.  So if you don't wish to make
a bunch of useless and repetitive swords, use some that have been declared
already.



=== The #ROOMS section

The rooms in your area are what make your area.  It is here that the players
meet your mobs and fight for their lives.  Remember these rooms set the
atmosphere of the area.  Go beyond just regular descriptive words, use far
out language, have a thesaurus handy when writing your rooms so you can use
that one exact word that expresses what the room is trying to convey. 
I can't stress enough that your descriptions even if short have to create the
atmosphere.  Even the room string can add to the affect.
The syntax of this section is:

    #ROOMS
    {
     #<vnum:number>
     <name:string>
     <description:string>
     <area:number> <room-flags:number> <sector-type:number>
     {
         D <door:number>
         <description:string>
         <keywords:string>
         <locks:number> <key:number> <to_room:number>
     }
     {
         E
         <keywords:string>
         <description:string>
     }
     S
    }
    #0

The 'vnum' is the virtual number of the room.

The 'name' is the name of the room.

The 'description' is the long multi-line description of the room.

The 'area' is obsolete and unused.  Rooms belong to whatever area was most
recently defined with #AREA.

The 'room-flags' describe more attributes of the room.
ROOM_ flags:
  DARK                 1       need a light source
  NO_MOB               4       no mobs may enter
  INDOORS              8       room is indoors
  UNDERGROUND	      16       room is underground (useful for avoiding sun)
  PRIVATE            512       only 2 people allowed (or 1 mob, 1 player)
  SAFE              1024       no pkilling
  SOLITARY          2048       only 1 person allowed
  PET_SHOP          4096       A pet shop
  NO_RECALL         8192       Can't recall
  CONE_OF_SILENCE  16384       No speech/spells/communication channels
  ARENA            32768       May attack anyone, No xp loss upon death

The 'sector-type' identifies the type of terrain.  This affects movement cost
through the room.  Certain sector types (air and boat) require special
capabilities to enter.

SECT_ types:
  INSIDE          0
  CITY            1
  FIELD           2
  FOREST          3
  HILLS           4
  MOUNTAIN        5
  WATER_SWIM      6
  WATER_NOSWIM    7
  UNDERWATER      8
  AIR             9
  DESERT         10

Unlike mobiles and objects, rooms don't have any keywords associated with
them. One may not manipulate a room in the same way one manipulates a mobile
or object.

The optional 'D' sections and 'E' sections come after the main data.  A 'D'
section contains a 'door' in the range from 0 to 5:

     0    north
     1    east
     2    south
     3    west
     4    up
     5    down

A 'D' command also contains a 'description' for that direction, and
'keywords' for manipulating the door.  'Doors' include not just real door,
but any kind of exit from the room.  The 'locks' value specifies special
features about a door, and there are several combinations.  Doors can be
bashproof, pickproof, and passproof.  The following table gives the 'locks'
value and how the door will be set for each acceptable value:

      value  pickproof  bashproof  passproof  eatkey
        1        no         no         no       no
        2       yes         no         no       no
        3        no        yes         no       no
        4       yes        yes         no       no
        5        no         no        yes       no
        6       yes         no        yes       no
        7        no        yes        yes       no
        8       yes        yes        yes       no
        9        no         no         no       yes
       10       yes         no         no       yes
       11        no        yes         no       yes
       12       yes        yes         no       yes
       13        no         no        yes       yes
       14       yes         no        yes       yes
       15        no        yes        yes       yes
       16       yes        yes        yes       yes

The 'key' value is the vnum of an object which locks and unlocks the door.

Lastly, 'to_room' is the vnum of the room to which this door leads.

You must specify two 'D' sections, one for each side of the door.  If you
specify just one then you'll get a one-way exit.

An 'E' section (extended description) contains a 'keywords' string and a
'description' string.  As you might guess, looking at one of the words in
'keywords' yields the 'description' string.

The 'S' at the end marks the end of the room.  It is not optional.

The outhouse from the githzerai castle will serve to illustrate most of the
commands.  Including an extra description that adds flavor to the room. 
With the extra descriptions and the right wording, you can make your rooms
come alive.

#15017
Outhouse~
     You stand in a small revolting outhouse.  There is a little box like
chair with a hole cut in the middle.  From this hole a faint brownish mist
pours forth.  You have to hold your breath to prevent yourself from releasing
your last meal.  The walls are covered with mild and the seat is beginning to
rot.  Just before the hole, the floor is wet.

The only exit is to the west, thank god you left the door open.
~
0 1 0
E
hole~
     You hold your breath and plug your nose to look in the hold.  At     
the bottom you see a large pile that does not look pleasant.  Your       
last meal comes bubbling up and spews forth adding to the pile.  You  
quickly stand straight up and notice that everything now looks blurry.    
You stand for a second with your head out of the door to clear yourself. ~
D1
The door is the only way out of this smelly and sickening place. ~
door~
1 -1 15016
E
door~
The door on this side is covered with more scratch marks.  It's as if the
people who come in here don't want to be here for long.... ~
S



=== The #RESETS section

The most important section of the area, and the easiest to mess up.  It is
here that you place your mobs and equip them.  Make sure you use the proper
location flags.

To reset an area, the server executes each command in the list of reset
commands once.  Each area is reset once when the server loads, and
again periodically as it ages.  An area is reset if it is at least 3
area-minutes old and is empty of players, or if it is 15 area-minutes
old.

An 'area-minute' varies between 30 and 90 seconds of real time.  The
average is 60 seconds.

The syntax of this section is:

    #RESETS
    {
     * <comment:to_eol>
    }
    {
     M 0 <mob-vnum:number> <limit:number> <room-vnum:number> \                
    <comment:to_eol>
    }
    {
     O 0 <obj-vnum:number> <:number> <room-vnum:number>      \
     <comment:to_eol>
    }
    {
     P 0 <obj-vnum:number> <:number> <obj-vnum:number>       \
     <comment:to_eol>
    }
    {
     G 0 <obj-vnum:number> 0  <comment:to_eol>
    }
    {
     E 0 <obj-vnum:number> 0 <wear_loc:number> <comment:to_eol>
    }
    {
     D 0 <room-vnum:number> <door:number> <state:number>     \
     <comment:to_eol>
    }
    {
     R 0 <room-vnum:number> <last-door:number> <comment:to_eol>
    }
    S

The 'resets' section contains a series of single lines.  The backslashes and
line splitting above are for readability; they are not part of the file
format. Because of the end-of-line comments, this section is not as free-
format as other sections.

The reset commands are:
    *     comment
    M     read a mobile 
    O     read an object
    P     put object in object
    G     give object to mobile
    E     equip object to mobile
    D     set state of door
    R     randomize room exits
    S     stop (end of list)

The '*' lines contain comments.  The 'S' line is the last line of the
section.

Every other command contains four numbers (three for the 'G' command).  The
first number is ignored.  The next three (or two) numbers are interpreted as
follows:
    
For the 'M' command, the second number is the vnum of a mobile to load.  The
third number is the limit of how many of this mobile may be present in the
world if the mobile is NOT sentinel.  NOTE, world! not room.  BUT, if the
mobile is set to be sentinel, the third number is limit present in the room.
The fourth number is the vnum of the room where the mobile is loaded.

For the 'O', 'P', 'G', and 'E' commands, the second number is the vnum of an
object to load.  The third number is ignored.

For the 'O' command, the fourth number is the vnum of the room where the
object is loaded.  The object is not loaded if the target room already
contains any objects with this vnum.  The object is also not loaded if any
players are present in the area.

For the 'P' command, the fourth number is the vnum of a container object
where the object will be loaded.  The actual container used is the most
recently loaded object with the right vnum; for best results, there should be
only one such container in the world.  The object is not loaded if no
container object exists, or if someone is carrying it, or if it already
contains one of the to-be-loaded object.

For the 'G' command, there is no fourth number.  If the most recent 'M'
command succeeded (e.g. the mobile limit wasn't exceeded), the object is
given to that mobile.  If the most recent 'M' command failed (due to hitting
mobile limit), then the object is not loaded.

For the 'E' command, the fourth number is an equipment location.  Be careful
where you equip the mobile or you might end up with a breast plate used as
a weapon.  

If the most recent 'M' command succeeded, that mobile is equipped with the
object.  If the most recent 'M' command failed, then the object is not loaded.

Equipment wear locations:
  NONE         -1
  LIGHT         0
  FINGER_L      1
  FINGER_R      2
  NECK_1        3
  NECK_2        4
  BODY          5
  HEAD          6
  LEGS          7
  FEET          8
  HANDS         9
  ARMS         10
  SHIELD       11
  ABOUT        12
  WAIST        13
  WRIST_L      14
  WRIST_R      15
  WIELD        16
  HOLD         17
  WIELD_2      18

All objects have a level limit, which is computed by inheritance from the
most recently read 'M' command (whether it succeeded or not) in 'area_update'
in 'db.c'.  As distributed, an object's level equals the mobile level minus
2, clipped to the range 0 to 50.

For the 'D' command, the second number is the vnum of a room.  The third
number is a door number from 0 to 5.  The fourth number indicates how to set
the door: 0 for open and unlocked; 1 for closed and unlocked; 2 for closed
and locked.

Room exits should be coherent: if room 1 has an exit to room 2, and room 2
has an exit in the reverse direction, that exit should go back to room 1.
This doesn't prevent one-way exits; room 2 doesn't HAVE to have an exit in
the reverse direction.

For the 'R' command, the second number is the vnum of a room.  The third
number is a door number.  When this command, the doors from 0 to the
indicated door number are shuffled.  The room will still have the same exits
leading to the same other rooms as before, but the directions will be
different.  Thus, a door number of 4 makes a two-dimensional maze room; a
door number of 6 makes a three-dimensional maze room.

Use of both the 'D' and 'R' commands on the same room will yield
unpredictable results.

Any line (except an 'S' line) may have a comment at the end.



=== The #SHOPS section

The syntax of this section is:

    #SHOPS
    {
     <keeper:number>                                        \
     <trade-0:number> <trade-1:number> <trade-2:number>     \                 
     <trade-3:number> <trade-4:number>                      \
     <profit-buy:number> <profit-sell:number>               \
     <open-hour:number> <close-hour:number>                 \
     <comment:to_eol>
    }
    0

Like the #RESETS section, the #SHOPS section has one command per line.

The 'keeper' is the vnum of the mobile who is the shopkeeper.  All mobiles
with that vnum will be shopkeepers.

The 'trade-0' through 'trade-4' numbers are item types which the shopkeeper
will buy.  Unused slots should have a '0' in them; for instance, a shopkeeper
who doesn't buy anything would have five zeroes.

The 'profit-buy' number is a markup for players buying the item, in
percentage points.  100 is nominal price; 150 is 50% markup, and so on.  The
'profit-sell' number is a markdown for players selling the item, in
percentage points. 100 is nominal price; 75 is a 25% markdown, and so on. 
The buying markup should be at least 100, and the selling markdown should be
at most 100.

The 'open-hour' and 'close-hour' numbers define the hours when the shopkeeper
will do business.  For a 24-hour shop, these numbers would be 0 and 23.
Everything beyond 'close-hour' to the end of the line is taken to be a
comment.

Note that there is no room number for a shop.  Just load the shopkeeper
mobile into the room of your choice, and make it a sentinel.  Or, for a
roving shopkeeper, just make it non-sentinel.

The objects a shopkeeper sells are exactly those loaded by 'G' reset commands
for that shopkeeper.  These items replenish automatically.  If a player sells
an object to a shopkeeper, the shopkeeper will keep it for resale if he, she,
or it doesn't already have an identical object.  These items do not
replenish.

See the #SHOPS section in midgaard.are or mirror.are for good examples.


=== The #SPECIALS section

Use this section to make your mobs mages, clerics etc...

The syntax of this section is:

    #SPECIALS
    {
     * <comment_to_eol>
    }
    {
     M <mob-vnum:number> <spec-fun:word> <comment:to_eol>
    }
    S

Like the #RESETS section, the #SPECIALS section has one command per line.

The 'M' command assigns 'spec-fun' to all mobiles of with virtual number
'mob-vnum'.  All spec-fun's are assigned by name.  An 'M' line may have a
comment at the end.

SPEC-FUNS are included below.

The following special functions are available for mobiles:

spec_breath_any			Dragon breath randomly chosen from the 5 below
spec_breath_acid		Acid Breath
spec_breath_fire		Fire Breath
spec_breath_frost		Frost Breath
spec_breath_gas			Gas Breath
spec_breath_lightning		Lightning Breath
spec_cast_adept			Healer
spec_cast_cleric		Combative Cleric 
spec_cast_ghost			Undead ghost (repop during night, gone by day)
spec_cast_judge			Combative Mage in Mega1.are
spec_cast_mage			Combative Mage (generic)
spec_cast_psionicist		Combative Psionicist
spec_cast_undead		Undead (generic)
spec_executioner		Executioner
spec_fido			Corpse-eating mobile
spec_guard			Midgaard Cityguard
spec_janitor			Midgaard Janitor
spec_mayor			Midgaard Mayor
spec_poison			Poisonous Bite
spec_repairman			Bashed Door Repairman
spec_thief			Pick-pocketing Thief

An example from draconia.are would be thus:

M  2243 spec_breath_any



=== The #GAMES section
( Games and gambling structure developed by Thelonius for EnvyMud )
( Furter coding by Maniac and later by Zen )

Use this section to allow your mobs to host gambling games.

The syntax of this section is:

    #GAMES
    {
     * <comment_to_eol>
    }
    {
     M <mob-vnum:number> <game-fun:string> <bankroll:number>  \
       <max_wait:number> <cheat:number>                       \
       <comment:to_eol>
    }
    S

Like the #RESETS and #SPECIALS sections, the #GAMES section has one command
per line.

The 'M' command assigns 'game-fun' to all mobiles of with virtual number
'mob-vnum'.  All game-fun's are assigned by name.

The 'bankroll' is the amount of gold that the croupier (the mob running
the game) has when it is loaded.  When the bankroll goes below zero, the
mob shuts down its game.

The 'max_wait' value is the number of PULSE_MOBILE's the croupier will wait
for each person to make a decision.  PULSE_MOBILE is defined in merc.h, and
is currently 1 second per pulse.  The wait between rounds depends upon the
number of players, not 'max_wait'.

If 'cheat' is non-zero (meaning TRUE), this mobile will cheat at the given
game, if such code is in place.

An 'M' line may have a comment at the end.

The following game functions are available for mobiles:

game_blackjack	(Not yet here)	Blackjack or twenty-one, dealer participates
game_u_l_t			Upper-Lower-Triple, a dice game
game_high_dice			High dice, a dice game
game_seven			Seven, a dice game

Here is an example of a #GAMES section:

#GAMES
*
M  3160 game_u_l_t		100000	  4	0	/* Croupier    */
M  3161 game_blackjack		1000000   8	0	/* Dealer      */
*
S



=== The #$ section

The syntax of this section is:

    #$

This section marks the end of an area file.  If you concatenate several area
files into one, remember to delete the terminating '#$' from all but the last
file.  Conversely, if you split area files, remember to terminate each new
file with a '#$'.

=== Spells

The following is a list of spells which can be used in EnvyMud.  These names
would appear in the appropriate locations for wands, scrolls, staves, potions,
and pills.  Note that staves typically are only useful with area-affect spells
(TAR_IGNORE) or specialized spells (like create spring).

	acid blast		faerie fire		acid breath
	adrenaline control	faerie fog		fire breath
	agitation		fireball		frost breath
	armor			flamestrike		gas breath
	aura sight		flaming shield		lightning breath
	awe			flesh armor		meteor swarm
	ballistic attack	fly                     chain lightning
	biofeedback		gate                    vortex lift
	bless			giant strength          mass vortex lift
	blindness		harm                    home sick
	burning hands		heal                    detect good
	call lightning		identify                dispel good
	cause critical		inertial barrier        portal
	cause light		inflict pain            nexus
	cause serious		intellect fortress
	cell adjustment		infravision
	change sex		invis
	charm person		know alignment
	chill touch		lend health
	colour spray		levitation
	combat mind		lightning bolt
	complete healing	locate object
	cone of silence		magic missile
	continual light		mass heal
	control flames		mass invis
	control weather		mental barrier
	create food		mind thrust
	create sound		mute
	create spring		pass door
	create water		poison
	cure blindness		project force
	cure critical		protection
	cure light		psionic blast
	cure poison		psychic crush
	cure serious		psychic drain
	curse			psychic healing
	death field		refresh
	destroy cursed		remove curse
	detect evil		remove silence
	detect hidden		sanctuary
	detect invis		share strength
	detect magic		shield
	detect poison		shocking grasp
	detonate		sleep
	disintegrate		stone skin
	dispel evil		summon
	dispel magic		teleport
	displacement		thought shield
	domination		turn undead
	earthquake		ultrablast
	ectoplasmic form	ventriloquate
	ego whip		weaken
	enchant weapon		word of recall
	energy containment
	energy drain
	enhance armor
	enhanced strength

If you have any questions about area writing, please contact any of the
immortals on EnvyMud, or perhaps get in touch with Silence at
ak709@freenet.carleton.ca.

Now that you have read how to make the area, you need to know in what to make
it in.  I suggest you make it in a text editor, or you can use an application
like word perfect 5.1 by using "Text Out" then selecting DOS file.  This way,
you can spell check your area before handing it in.


----------------------------Mud Administrator Section-----------------------

=== Booting and Testing Areas

When the Envy server starts, it reads a file named 'AREA.LST' in the current
directory.  This file contains a list of all the area files to read in.  To add
or delete areas, simply edit area.lst.

The server reads all of the area files into memory once at load time and then
closes them.  Thus you can edit area files while the server is running.
Changes will take effect the next time the server boots.  Because the server is
completely memory-based, zone resets are fast, too.  (And paradoxically, moving
to a memory-based system allowed certain memory optimizations to be made,
cutting memory usage by 50% from Merc 1.0).

You can test areas by running Envy in a different directory with a different
'AREA.LST' file with new areas dropped into it.  Setting up an appropriate
directory structure is an exercise for the student.  (You DID say you're
running a mud because you wanted to learn more about system administration,
right?)  Hint: you can run a program in another directory just by invoking its
full name: '../src/envy', for example.

The server reports syntax errors, including the area file name and a line
number.  Take the line number with a grain of salt; some kinds of errors cause
the server to run on for quite a few lines before ultimately detecting the
error.

The server also reports semantic errors, such as references to non-existent
mobiles, objects, or rooms.

Error recovery is simply not possible without far more sophisticated input
parsing than we're willing to write.  (Hey, feel free to write your own.)
Thus the server exits after reporting any error.  Envy takes only a few seconds
to load, however, so it's quite practical to use the whole server as a syntax
checker.



=== Compressing the Area Files

It is possible to run Envy with a single combined, compressed area file.
Here's how to do this on a Unix system:

(1) In 'AREA.LST', remove the last line (the '$' line).

(2) Execute the command:

	cat `cat AREA.LST` | compress > all_area.Z

(3) Edit 'AREA.LST' again.  Insert a '-' at the beginning of every line.
    Do not put any spaces between the '-' and the file name.  Put the last
    '$' line back at the end of the file.

(4) Edit 'startup'.  Change the line:

	../src/envy 4000 >&! $logfile

    to:

	zcat all_area.Z | ../src/envy 4000 >&! $logfile

(5) Test the changes so far.  Envy should start up normally, although it
    may take a few seconds longer to zcat everything.

Now you can remove all the original *.are files.

Notice that all of the compression and decompression takes place outside of the
Envy server.  Thus, you can substitute any archiving program of your choice, as
long as it can write its output to standard output.

You can recover the original areas simply by running 'uncompress all_area.Z'
and dissecting them out of all_area.

From the server's point of view, when an area file name starts with '-', it
simply reads standard input for the area, terminating at '#$' as usual (but
without closing standard input).  Diagnostic messages are given with the full
name (e.g. '-arachnos.are'), but the line number will be reported as zero.

You can freely mix areas from standard input with ordinary area files.  Thus,
you could compress all the Envy standard zones into a file such as envy_area.Z,
prefixing them with '-' in 'AREA.LST'.  Then you could add your own areas
anywhere in the file (beginning, middle, end, wherever your areas need to go),
and omit the '-' on the lines for your areas.

The server will take a little longer to load with compressed area files,
because 'zcat' needs time to run.  This is offset by a reduction in time spent
opening disk files.  After loading, the server has all of the area database in
memory and never rereads the files.  Thus, there is zero performance impact
on server operation after loading.



=== Memory Usage

In order to simplify the code, the EnvyMud server has a fixed maximum size on
strings in the area database.  This size is defined at the beginning
of 'ssm.c'.  As distributed, this size is:

#define MAX_CHUNKS 33

This size is about 6% (100k) larger than needed for the areas we
distribute.  Thus, you can add about 2 more areas without touching the
server at all.  The server will tell you when the string table
overflows, and you can simply increase the maximum limit and
recompile.  Any memory overflow is handled by SSM and will not
adversely affect the game.

The immortal 'memory' command will show you memory usage from within
the game.  Memory overflow will be noted using the 'memory' command.

There is no other limit on area sizes or memory usage.

We decided to use a fixed size because it simplifies our job.  It also allows
significant performance improvements: compare our load time and memory usage
versus other Diku muds with the same quantity of areas.
