
                      AIME codebase User's Manual
                       version 0.59 (April 2001)
 
                          written by Slate
                          (noelg@acm.org)


Note:  This guide is far from finished and is very incomplete.  If you would
       like to see some info in here, please contact Slate (noelg@acm.org)

Index:

1.  Introduction
2.  File Layout
3.  Installation and the First Run
4.  Access Control, Security and Permissions
5.  Managing the Network Connection
6.  User Accounts
7.  Administrative Commands
8.  Login Sequence
9.  The Game Environment
10. Entities, MudObjects, and their Interaction
11. Mud Engine Performance Statistics
12. Tips for Creating Your World


1. Introduction

   The Advanced Interactive Mudding Environment (AIME) is a comprehensive 
mudding system designed to be extremely flexible and robust.  The code was 
designed with the intent of providing a MUD engine capable of supporting most 
anything a builder or game implementor could come up with.  It is designed 
to eliminate the requirement for a coder to run a mud.  With the AIME mud 
engine, things can be added online and rarely will an implementor need to 
access the unix shell.
   It includes a fully functional builder port, capable of modifying most
aspects of the game without ever needing to access the Unix shell.  Various
objects and specials code permit the game implementor to design special
events all throughout the game, from a sword that freezes the enemy to a
lever that moves a secret wall when pulled.   The game port contains many
game features, from mobiles that hold conversations to boats, rope ladders,
comprehensive combat system, and a wide possibility of weapons and armor.'
It also contains many tools designed to allow the game implementor to
fully administrate the mud easily and quickly, as well as monitor the
performance of the code.
   With flexibility comes complexity.  However, AIME has been designed to
consolidate many functions into several easy-to-understand and structured
commands.  A game implementor can start out simple and gradually progress to
more complex features as they mold their world.  Granted, creating an entire
world with AIME will take some time, as with any mud engine, but once it is
finished, the mud will end up being anything your imagination can dream up.
   This user's manual will describe the installation process and how to
quickly get up and running so you can start playing with the MUD engine.  It
will describe security, creating user and administrative accounts, how the
game environment works, and how objects interact with each other.  It will
provide tips for creating and maintaining a rich and vibrant world that will
attract numerous players.


2. File Layout

   The files are organized in several directories.  On the main aime
directory (henceforth referred to as the base directory), it contains several
directories, each containing a subset of information.  The 'src' directory
contains the source code.  If you do modify the source code, remember that
this will cause problems when you try to upgrade as new versions of AIME
come out.  What may be a better approach is to get your changes approved
and included in the AIME distribution.  Supplimenting the 'src' directory 
is the 'include' directory which contains the code headers.  If you are
not a coder, you will never need to worry about these two directories after
the installation is complete.
   The 'areas' directory stores all static area information.  These files 
store all information about a zone so it can be loaded into memory and into 
gameplay.  These files can only be modified using the builder port and provide
static information about the areas.  The MUD engine does a search for all
.area files on startup and loads any found in the 'area' directory.  Errors
detected during load are recorded in the error log, discussed later in this
document.
   The 'data' directory stores information on races, levels, quests, and
an assortment of other information.  It stores info files, help files, user
data files, and bulletin information.  In the 'data' directory, the 'aime.conf'
file can be found.  It provides configuration control for the mud engine,
allowing the mud implementor to change settings on the way the mud engine
runs.  
   The 'utils' directory contains utilities useful in the operation of 
the MUD.  It includes a password encryptor used for generating the master
user account password and a conversion utility used in converting area and
data files from older versions or other formats (Aber, SMAUG, etc) to the
latest AIME format.
   The 'build' directory holds temporarily saved builder files.  This
permits the builder to save their changes without introducing them into the
game before they are ready.
   If you have the debian binary release or the win32 (Microsoft Windows)
version, the src, include and utils directory will not be there.  Several
other directories may be missing but will be created the first time the MUD
is start up.  
   In the base directory are several files that help manage the AIME MUD 
engine.  The 'package' file creates a package of all information specific to 
your mud.  This includes the area files, data files, and configuration files.
In the win32 environment, this script will not work.  Backups will need to 
be done on all .area files in the area directory and all .dat files in the 
data directory by hand.
Basically, the 'package' script generates a tar package that contains all the
files that make a MUD unique.  It can be used to generate occasional backups
of the files or package these files for distribution.  It is used with the
command 'package <name>' (without ' or <>) where name is the name you would
like to give the package.  It will package the files into a single file with
the name <name>_pack.tar.gz.
   To decompress a package and install the files, one should first place
the <name>_pack.tar.gz file into the base directory. Then type the following
to install the package into the directories: 'install_package <name>' where
<name> is the name of your package.  Notice that it will not work by including
the .tar.gz in there, so 'install_package <name>_pack.tar.gz will not work. 

3. Installation and First Run


Linux Install:

   The following instructions provide details on how to install the codebase
from both the source code and the Debian distribution.  The source code must
be compiled before it will work, while the Debian distribution includes the
binary for a i386-based system along with installation scripts to install
the system.
   If you are using the sourcecode distribution, the next step is to compile
the source.  First, create the Makefiles by running the configure script.
You should go to the base directory and type "./configure" and if that finishes
without any errors, then type "make install" and let the compiler do the rest.  
If you should happen to get an error stating that it could not write to the 
/usr/local/share directory, then you will have to type "make" and move the 
aime/src/mudbin, aime/utils/makepasswd, and aime/utils/converter/convert to 
the aime/bin directory.
   Once unpacked and installed, the mud should be fairly simple to set up.  The
defaults in data/aime.conf should work but it would be wise to change a few 
things.  IMPORTANT: MAKE SURE BASEDIR IS SET TO THE FULL PATH OF THE AIME
MAIN DIRECTORY OR IT WILL NOT WORK.  This means that if you install in
/home/mydir/aime, you should set AimeDir = /home/mydir/aime in the aime.conf
file. 

Win32 Install:

   For the win32 binary (.exe file), all you need to do is unzip it in a
directory.  Once this is done, it is very import to SET THE PATH OF THE
AIME DIRECTORY IN AIME.CONF.  The BaseDir field in the aime.conf file,
located in the data directory should be set to the location of the base
aime directory.  So if you install it on the D drive, it would be set up as:
BaseDir = D:\aime

  
Both installs:

   Next, ensure the Gameport and Buildport are set to the ports you want
the game port and builder port to use.  If you expect the mud to crash, you 
should undefine the Daemonize feature.  This way you can get a core dump to
debug.  The Debian distribution, however, has been compiled with optimization
flags set and therefore will not provide a very good core dump in the event of
a crash.  The best approach will be to send what you did to cause the crash to
noelg@acm.org so it can be eliminated from the next distribution.  Autowiz can 
be used to give everyone who logs on full priviledges.  You will probably want 
to ensure that is undefined as if it is defined, any joe player can log on and 
mess with things.  Finally, set the MasterName and MasterPasswd.  The MasterName 
should be a name you will rarely ever use.  You will use it the very first 
time you logon to the mud to give your character full priviledges.  You can
generate a password for use by running aime/bin/makepasswd and copying the
encrypted string into aime.conf.  The first time you login with this username,
it is important to use the same username and password that you entered into
aime.conf.  It will make you create a character, but the character will have
full priviledges.  If this does not work properly, you can set AutoWiz to
yes momentarily so you can create a new character with full privileges.  
   To start up the mud in linux, you simply need to run the 'mudbin' 
executable.  If you don't have daemonize defined in aime.conf, you will need
to run it in the background with 'mudbin &'.  For windows users, running
mudbin.exe (also found in the bin directory) will bring up a management
window.  Simply hit the "Start Mud" button and as long as you don't have
any errors, it should start up.  For both platforms, you may be prompted to
create directories.  You should say yes to these.
   Once logged in, you can use that master account to create other players 
who are full powered.  One word of caution, it would be more secure to 
define a master account that you will never use except on the first login, 
as it is more secure to use this master account to bump your normal character 
up to full power and never login with the master account again.
   To permit your character to login at the builder port, you will need to add 
your host to the bhosts allow list.  Type 'help bhosts' for the syntax.  Typing
ds'help' will give you a list of commands and typing 'help <command>' will 
provide help on a specific command.
   To use the builder port, reference the builder tutorial included in the aime
documentation.  Once you have created a location, you can ensure the players
enter the game at that location by typing 'set defstart <locname>@<area>' in 
the game port. 
   A zone called Courtland and Global has been included in the distribution to
demonstrate many of the capabilities of the code.  Your character will start in
the town of Courtland initially, but you can change it as necessary.  The
town is really for demonstration purposes and while I wouldn't force you not to
use it, you should really develop your own world.  Also, not everything has
evolved in the zone along with the code, so you may get some errors when using 
it.

4. Access Control, Security and Permissions

   The AIME codebase has several means of distributing the proper rights to the
proper individuals.  The system is designed to prevent those you don't want on
the mud from logging on, prevent regular players from gaining administrative
rights, and allow the administrator to give builders only those rights needed
for building and administrators only those rights needed for basic game admin.
   The first security barrier exists when the player connects to the mud.  On
both the game port and builder port, an access list exists that can allow only
a set list of hosts to gain access, or deny a set list of hosts from gaining
access.  First, allow by default or deny by default must be set in aime.conf.
If GameAllowDefault in aime.conf is set to yes, then hosts are allowed unless
they are in the 'bhosts' list (discussed later).  If GameAllowDefault is set
to no, then hosts are denied access unless listed in the 'bhosts' list.  With
BldrAllowDefault, the same applies except the list of hosts is found in the
'banhosts' list.
   Both the 'bhosts' and 'banhosts' lists are accessed with the commands
'bhosts' and 'banhosts' respectively.  By just typing 'bhosts', one can see
the default security setting (Allow by default, Deny by default) at the top
and then the lists of hosts either allowed or denied, depending on the default
security setting.  'bhosts' provides the list for access to the builder port
and 'banhosts' provides the list for access to the game port.
   To add a host to the game port list, one simply uses the command 
'banhosts add <host or IP>'.  The banhosts and bhosts command allow for wild
characters (the * character).  This way, you can ban a group of hosts or IP
addresses at once.  An example of this would be '*.home.com' or '192.168.*'.
   To remove a host or IP address from the banned list, use the command
'banhosts del <host or IP>'.  The <host or IP> must be exactly as it is written
when you display the banned host list.  You can display the banned host list
by typing 'banhosts' without any parameters.  The same rules apply to the
builder port ('bhosts' command).
   The recommended way to control access is to allow access by default on the
game port and deny access by default on the builder port.  This way, you can
ban unwanted hosts on the game port but explicitly specify hosts you want to
connect to the builder port.  If in the developmental stages where you don't
want anyone but those involved with the creation of your mud to access the
game port, you may want to set deny by default. 
   On the game, user permissions are influenced by a combination of Command
Flags and Administrator Flags.  For the most part, each command on the builder
port and the game port has a flag associated with it in the Command Flags.  In
order to use a command, the Command Flag must be set.  This allows fine tuning
of user permissions.  If a player is abusing the shout command, you can turn off
their shout flag which will prevent them from using the command.  This allows
for disciplinary action without requiring kicking them off to stop their abuse.
Players who want to help with specific administrative tasks can do so without
requiring they own the "keys to the castle".
   Command flags can be set or cleared with the 'comflag' command.  By typing
'comflag <user> <flagname> on', an administrator can set the flag indicated by
<flagname> on the user indicated by <user>.  Command flags can be displayed by
typing 'comflags' without any parameters.  Finally, command flags can be turned
off by typing 'comflag <user> <flagname> off'.
   Administrator flags indicate specific administrative capabilities for
users.  It allows users to see administrative messages and perform
administrative tasks throughout the MUD.  Setting, clearing, and listing
administrative flags use the 'adminflag' command in the same way as the 
'comflag' command is used.
   A note of caution, certain command flags, if set, will provide the capability
to do anything on the MUD.  The biggest one is the 'comflags' command flag.  If
this is set, users can basically give themselves any rights they wish.  With the
'adminflag' command flag, they will be able to give themselves any 
administrative flags they wish.
   While the command and administrative flags allow fine-tuning of user's 
rights, it can become overwhelming to have to set all these flags for each 
administrator.  This is where the 'mask' command comes in useful.  Masks are 
defined on the builder port (see the builder tutorial for instructions) and 
provide a means of applying a permissions "template" to users.  This means 
you define all the permissions you want a 'builder' to have, for example, and 
when you type 'mask <user> builder set', it will set all the permissions you 
have defined for a builder to the user indicated by <user>.  You can create 
as many masks as you wish and use them to set permissions on users.  The 
'players' mask is used by the game port to assign to players when they enter 
the game.  It must be there or users will not get any permissions and will
not be able to run any commands.  If it is missing, check in your distribution 
for the latest copy.

5. Managing the Network Connection

   The network connection consists of two listening ports.  One exists to
handle game port connections while the other handles builder port connections.
These two ports are seperated to keep the game world and development world
independant of each other.  However, in some situations you may only have
one port available for use.  You can combine these two network connections
into one by giving them the same port in aime.conf.  When a user logs in,
it will check to see if their site has access to the builder port and if
they do, it will give them a menu to select from so they can choose the port
they want to connect to.
   To see which sockets are being used, the sockets command can be used.
It will provide a list of sockets and the username who owns them.  To
disconnect a socket (for instance someone in the middle of logging on
who has sat in the login window for hours), you can use the 'disconnect'
command.  The help function can provide more information on these commands.

6. User Accounts

   User information is stored in the data/users directory.  The user data file 
stores all their attributes as well as the items in their inventory when they 
quit.  As users are created, they are stored in data/users/x where x is the
letter of their first name.  This file stores their password, description,
attributes, abilities, items carried, and many other player attributes.
   To remove a user's player file while online, one only needs to use the
deleteuser command.  If they are online, it will also kick them off.  To
change their attributes, the set command may be used.  Using "help set" will
give details on how to use this command.  It can be used to change a user's
strength, health, add abilities, add chatlines, and many other settings.


7. Administrative Commands

   This will describe game administrative commands.  Going to put off writing 
this until we get more commands.

8. Login sequence

   The login sequence for new players provide many features to permit players
to tailor-create their character.  From race selection to fine-tuning with
talents, it provides a way to allow the character the initial variation one
finds with prospective apprentices in a trade.  Not every child is alike,
some are stronger while others are smarter.  Rather than use a random roll
of the dice, the AIME system permits the players to choose which advantages
and disadvantages they wish to provide themselves.  They then can choose the
path most advantageous to them or if they want a challenge, try to travel
the career path they are not initially inclined towards.
   When the player first connects to the game port, the game banner is
displayed.  This can be changed in the builder port by loading the area
'banners' and modifying the gamebanner.  See the builder tutorial on details
for doing this.
   The first entry in the login sequence asks for the player's name.  If the
name is not found in the user database, it asks if they really want to use
this player.  If no, it allows them to type their name in again.  If the player
selects yes, it enters the new character login sequence.  First, the player
must enter in their password twice.  Next, the player is asked if they wish
to use color...fairly self explanatory.
   The next login step is to select a race.  The race influences the initial
attributes of a player, the abilities the player starts out with, and how
the player looks initially to the others.  It can, depending on how you
tailor your world, influence how others deal with this player.  It influences
which tutorials the player runs through, though you can keep the tutorials
all the same across each race if you choose.  While later steps are optional,
selecting a race is mandatory for players in the AIME environment.  Details 
on creating Races are available in the builder tutorial.  
   Next, the player selects the sex whether male or female..fairly self-
explanatory.  After that, the player enters the tutorial chain.  By using
the tutorials specified in the race object, the player can be forced to
enter a tutorial or choose to enter themselves.  If no tutorials are specified
in the race object, this step is skipped.
   Once the tutorials are finished or if no tutorials existed for that race,
the player enters the inclination selection stage.  If no inclinations exist
for the player to choose from, this step is skipped.  However, if inclinations
exist for this player, the list is displayed and the player given the
opportunity to choose one.  The inclinations provide way to account for the
fact that not all of a particular race will be the same.  Some are stronger,
some are more dexterous, and some more intelligent.  The player may choose
which inclination they favor.  Details on creating Inclinations are available
in the builder tutorial.
   After the inclination selection stage, the player then enters the talents
selection stage.  If no talents exist, this stage is skipped.  If, however,
talents have been created, the talents will be displayed and the player
prompted to select talents.  If they do not have enough talent funds (set
in aime.conf) then they will not be able to assign a talent to themselves.
Talents can be used to set specific attributes, such as increasing strength
even more, adding specialty flags such as night vision, infrared vision, or
gives someone specific abilities.  It uses specials so the possibilities
are vast.
   Finally, the MUD engine asks the new player if they would like to
display the intro, which is the intro banner listed when one loads the
banner area.  For information on modifying this, see the builder tutorial.
After the intro is displayed, the player starts in the location specified
by their specific race.


9. The Game Environment

   This will describe the game environment, such as weather, time, etc as we 
code it in.


10.  Entities, MudObjects, and their Interaction

   Everything around the game that can be manipulated or manipulates players 
are considered Entities.  Mobiles, locations, weapons, armor, food, specials, 
and many other object types are all considered Entities.  Even Levels and 
Quests are Entity objects.


11.  Mud Engine Performance Statistics
12. Tips for Creating Your World








