Note:  this file, while useful, tends to run a little out of date.

------------------------------------------------------------------

                    ALTERING PHANTASMAL

                      INTRODUCTION

If you're serious about building your own MUDlib, you should realize
that Phantasmal builds on the Kernel Library for a reason -- you may
wish to do so instead of using this, and simply treat Phantasmal as
one more example MUDLib.  At a minimum you'll want to read up on the
Kernel Library.

You can find more stuff about developing based on Phantasmal at the
following URL: "http://phantasmal.sourceforge.net/Developing.html".

You can find more stuff about developing based on the Kernel Library
at "http://phantasmal.sourceforge.net/DGD/Kernel/".


                 OVERALL ORGANIZATION

Phantasmal does its best to conform to the spirit, not just the
letter, of the Kernel Library's restrictions and recommendations.  It
puts its libraries in /usr/XXX/lib, its clonable objects in
/usr/XXX/obj, and its daemons (objects that are instantiable, but that
keep only a single copy of their data and provide services) in
/usr/common/sys/ or /usr/System/sys.  All current lightweight objects
are in /usr/common/data, though that's not as fully spelled out by
the Kernel Library.

Code security is established by checking the previous_program(), among
other ways.  Security against non-admin players is quite good even
now, and we hope to keep it that way.  Scripts are in their infancy,
but they'll be a fine way to allow builders to do some coding without
letting them mess too much up.


                    SPECIFIC TASKS

To add a new locale (for instance Polish, Hungarian or Tengwar) you'll
want to change at least /include/phrase.h, /usr/System/sys/phrased.c
and the cmd_locales function in /usr/System/obj/user.c.  Phrased's
create() function sets up a lot of data structures -- make sure you
understand them and how to change them.  Eventually we may alter these
structures to be more dynamic.  That should make adding locales
easier.  But that will involve many objects (phrases, helpd, phrase
repositories, rooms, etc) being notified of a change in locales or
detecting it lazily.  In any case, unicode is not yet supported so
beware if you're dealing with a non-ASCII language like Chinese.
Planned Phantasmal changes, when completed, should allow better
terminal support, which will allow unicode support for some terminal
types.

You may want to have a look at /usr/common/sys/helpd.c and change the
exclude_path function.  It determines what directories will not be
checked during recursive descent to see if they contain helpfiles.
Particularly if you use a source-control system not based on RCS, CVS
or SCCS, you're likely to want to add to this (and submit the changes
back to me, please!).  You can also override the HelpD's operation by
registering help files one by one instead of directory by directory.
You'll need to override the upgraded() behavior as well, though.

Currently new Phantasmal-level commands go into
/usr/System/open/lib/userlib.c or /usr/System/lib/wiztoollib.c,
usually at the end of the file.  These commands run at that file's
full privilege level so you shouldn't allow anyone without absolute
full trust to write new commands.  There are a couple of sub-libraries
of wiztoollib, also in "/usr/System/lib/".  Some commands are better
added there.  Obviously, you can also add the commands to
/usr/game/obj/user.c or its equivalent.

You'll also need to add a user-visible name for the commands in
/usr/System/obj/wiztool.c for admin commands and in the user object
for player commands.


                   SPECIFIC LOCATIONS

If you're serious about making a real MUD happen, look through and
change absolutely every helpfile entry -- they're all found under
"/usr/game/help" and "/usr/game/help/admin" if you work based on
testgame.  Nothing says "unprofessional" (plus "lame", "sloppy",
and so on) like leaving stock MUDLib stuff unchanged in your MUD,
especially when it's wrong.  The help files contain a lot of contact
information, MUD policies and other stuff that's quite specific to
my personal server.  Look through and change it or you'll be
unpleasantly surprised by the contents.  And I mean it -- look
through and change *every* help file.  Add new ones as you add stuff,
too.  This is very, very important.  Have I said it enough times yet?

There's a system log under the "/log/" directory.  Make sure you know
what it is, how to use it, and what goes into it.  If you're not sure
where a particular entry comes from, find it in the code.  Grep is
your friend, or your editor's "find" feature if you're not using a
Unix variant or Cygwin.  You can alter what gets logged with
"/data/system/logd_channels.unq".  Figure out how it works.

Managers such as stringd.c, phrased.c, logd.c, userd.c and so on live
in either "/usr/common/sys" or "/usr/System/sys/".  Pretty much any
manager that can be removed from "/usr/System/sys/" already has been.
Understand why.  Hint: think security.


                   GENERAL GUIDELINES

Phantasmal allows for a serious amount of localization.  That means
the MUD allows reasonable translation to other languages.  At the
moment there's no unicode or other non-ASCII support, but it's at
least strongly possible in the infrastructure.  This is unusually good
by current (lousy) free MUD standards.  If you want to run a
Phantasmal-based MUD in a foreign language, let me know.  I'd be very
happy to get the localization stuff happening better, but I need test
cases before it feels like it's got a point.

You can take advantage of this.  Make sure that all your descriptions,
help files and all other text are localized to multiple languages.
Make sure that anything you add to the MUD is too.  Using the UNQ
parser and the UNQ phrase format is the easiest way to do this.  See
the help files in "/usr/game/help/" for examples.  More messages will
become localizable as time goes on.

Phantasmal provides an excellent help system -- at least by those same
lousy free-MUD standards.  It allows multiple names to link to the
same help entry and also does phonetic matching to see if what you
typed resembles a known help entry.  The current phonetic matching is
English-only, which will make sense if you think about it a bit --
phonetic matching is seriously different in languages with non-English
consonants, for instance, or languages not based on the Roman alphabet
(not that we have any yet).  Additional suggestions for how to improve
the help system are welcomed.

Understand the difference between objects that are instantiated
directly from LPC files and objects that are created from big data
files.  The Void, a room, is the former.  Help files are the latter.
If you can't find code for a given object, it may be because it has no
explicit, spelled-out LPC code at all, and is instead created based on
a simple template and a data file.  See simple_room for an example of
code that supports this.

There's a full binding system for associating UNQ templates with room
code.  You can find the binder files in "/data/system/".  Look for
files like "room_binder.unq" and "mobile_binder.unq".  From there,
look through the code until you understand what they do.

Know the Kernel Library.  Phantasmal does my humble best to conform to
its requirements, and may do even better in the future.  Understand
how its resource management works and how that interacts with having
administrative privileges of various kinds.  This is more subtle than
it sounds.

The wiztool is where an admin or builder gets his or her power.  You'd
better know what's in it and how to add more, hadn't you?  You'd also
better know why it has the security checks it has, and make sure you
add the right checks to anything you put in that file.  Ditto for
other locations where security matters like user.c and every system
manager in "/usr/System/sys/".  Again, you know why it matters that
it's in that directory, right?  I knew you did -- I'm just being
difficult.  When adding these checks, remember you're not really
defending against end-users except for actual commands.  You're
defending against untrusted admins, admins you've given a little
power.  They'll naturally try hard to poke big holes in your MUD by
calling your functions in ways you didn't intend.  Lucky you're ready
for them, hey?