  MAGIGATE.DOC                                                       Page  1
  ͸
               The Magic Gate version 1.08                                 
               Documentation  May/June '97                                 
               (C) Copyright 1995 - 1997 All Rights Reserved               
                 Joseph O'Connor                                           
  ;

        This game may be distributed in its original, unmodified form as
  long as no money is made off of it.  Please do not include the contents
  of this archive in any CD, collection, or whatever without express written
  permission of ME!

        Thanks for at least taking the time to look at this game.  I know
  there are hundreds and thousands of On-Line games available for Bulletin
  Boards these days.  Some are good, and some are not; hopefully this will
  at least be one you choose to put on your own board.  Some of its features
  are as follows:

  *  Designed to work in a multi-node enviornment.

  *  Easy and Powerful Configuration Program that lets you change nearly
     any aspect of the game.   
     
  *  Works with most BBS types (DOOR.SYS, SRDOOR, DORINFOX.DEF etc.)

  *  Included Creature creater.  Allow you to create as many creatures for
     each area as you want.

  *  Player editor that allows you to change any statistic of any character.

  *  Automatically weeds out inactive players after X many days.(configurable)

  *  Resurrects Dead players after X many days.(configurable)

  *  Six different character classes to choose from, each with their own
     special abilities.

  *  Twenty character levels in each class with class mastering.
  
  *  Players can fight each other.

  *  Players can pay for a room at night to be somewhat safe.  (There is a
     way to get into the room that is different for each class.)

  *  Characters have Shame and Luck characteristics which affect certain
     outcomes that are random.

  *  Clans/Masters.  Each character has his own teacher that he goes to.  You
     earn shame by attacking another student of your master.

  *  Guilds.  Characters can start their own "team" and build a hall where
     they can stay for the night and store their gems and gold.  
     
  *  Guild Masters can enter the description for the inside of the guild hall.
  
  *  Guild Guardians. Guild halls have a guardian that anyone who wants to 
     raid the guildhall must fight before they can enter.  The guardian is
     upgradable by the guild master only.

  MAGIGATE.DOC                                                       Page  2
  
  More Features :

  *  Error handling and reporting in a log file.

1.05
  *  New, flexible character flags that can be added, deleted, modified
     either through the scripting language or through external programming.
     Allows scripts to _remember_ what you did.

  *  Scripts can now be encoded to discourage people from reading through the
     code to figure out the solution to your module.

  *  Automatic patch feature. There is a slight change in the data from 1.04
     to 1.05. This feature detects which version data files you have and
     converts them if necessary.

  *  Improved handling on the on-line messaging system, including a frequency
     for checking online messages that is sysop configurable for faster/slower
     machines.

  *  Now has a chat room where you can hang out and talk to other players
     online.

  *  Chat Room Combat - Duke it out with your worst enemy while all your
     friends cheer you on, and see what is happening in the fight!

1.06
  *  Now with Game Random events.  Just sitting in the Town Square, a random
     event could happen to you!  These events are run as a script and are
     easily added to the game.

  *  Event Scheduler.  Want an event to happen at 4:00 p.m. every day?  You
     can do it in the newest version!  You can set it up to be run every day,
     every week, every Tuesday, etc...

  *  Creatures are now classified as a certain race.  Everything from Avians
     to Zombies are here.  This is going to work in conjunction with the
     modifications up and coming.  Not to worry, the new version is going to
     read in your old file just fine and add the default race to it.

  *  Weapons Armor and Shield Editor added to the configuration program.

1.07
  *  Can now have more items than a sword, armor and shield.  These items
     can also activate scripts based on what you do with them.
     Items can be added to the game via the scripting language as well as
     building up the item database.

  *  Easily install new areas using the Magicfg program.  Reads in a section
     of the script or a description file and adds it to the appropriate place.

  MAGIGATE.DOC                                                       Page  3
  
  Included Files :
  
  The following is a list of the files contained in the current release.

  MAGIGATE.DOC          :  This wonderfully-written documentation file.
  SCRIPTS.DOC           :  Documentation for creating TMG Add on scripts.
  EXTERNAL.DOC          :  Documentation for creating EXternal MODules for
                            TMG as well as the format of all the structures
                            used in the game.
  CONFIG.DOC            :  Documention on how to configure and optimize TMG.
  HISTORY.DAT           :  My own scribblings on what each version added to
                            the game and removed from my sanity.
  REGISTER.DOC          :  How to get more out of TMG than the average user.

  MAGIGATE.EXE          :  Huzzah, the main program.
  MAGIGATE.OVR          :  The other part of the main program.
  MAGICFG.EXE           :  The configuration program/editor.
  MAGITEXT.DAT          :  Contains the menus for the game. (no peeking!)

  EVENTS.DAT            :  The schedule for running events (See instrcutions
                            within the file itself for explanation)                             
  EXMODS.DAT            :  Sample file for adding EXMODS, this one will run
                            the Forest of Wolves Script.     
  RACES.DAT             :  Contains all the information about the races of the
                            creatures in the game.

  ARMOR.SHP             :  The shop file for the armor shop in the game.
  SHIELD.SHP            :  The shop file for the shield shop in the game.
  WEAPON.SHP            :  Wanna guess?

  FOREST.DAT            :  Contains the creatures for the forest.
  VALLEY.DAT            :  Contains the creatures for the valley.
  MOUNTAIN.DAT          :  Contains the creatures for the mountain.

  FOREST.SCR            :  The Afore mentioned Forest of Wolves script example
  STARTUP.SCR           :  A script file that is executed when the game is run
  CONFIG.SCR            :  This is used to configure some in-game options
  RANDOM.SCR            :  This is where the random events are stored

  <ITEMS DIRECTORY>     :  This is where the scripts for the items are kept.
                            They are numbed 1.scr ... XXXXXX.scr
  STOCKITM.SCR          :  This is the file that TMG uses to update the items
                            to the current version.  It contains all items.

  And That's it for the files that come with the program!  What you don't see
  there though, is a list of the files that you may eventually find on your
  hard drive in the directory you UNZIP it to...  A few are as follows:

  MAGIGATE.DOC                                                       Page  4
  
  Other Game Files :

  MAGIGATE.DAT          :  This file has the startup information that the
                            main EXE reads to communicate with your BBS.
  MAGISTAT.DAT          :  The file with all the nifty little setup info...
  MAINFLAG.DAT          :  Flag file for the main game and any scripts.

  PLAYERS.DAT           :  This one has all the player info in it. surprise!
  PLAYERS.OLD           :  This has the player info too.  Used as backup.
  USERXXXX.DAT          :  Mail for player XXXX.
  FLAGXXXX.DAT          :  Flag file for player XXXX.
  NODEXXXX.DAT          :  Messaging file for player XXXX.
  INVTXXXX.DAT          :  Inventory file for player XXXX.


  GUILDS.DAT            :  This has all the guild info in it.
  GUILDS.OLD            :  This has the guilds info too.  Used as backup.
  HALLXXXX.DAT          :  Guild hall description for guild XXXX.
  HALLXXXX.MSG          :  The messages on the board for guild XXXX.

  DEBUG.TXT             :  ASCII text file created by TMG for logging errors
                            and comments.
  DEBUG.OLD             :  Debug file from yesterday.

  NEWSX.DAT             :  The news file from X days ago.
  GRANK.ANS             :  ANSI guild ranking file.
  GRANK.ASC             :  ASCII guild ranking file.
  PRANK.ANS             :  ANSI player ranking file.
  PRANK.ASC             :  ASCII player ranking file.
  
  And it ends there right?  Well, no, you may also find a couple other .DAT
  files there if you create creatures for other realms.  Those realms are
  there for expansion right now as the forest only goes up to level 7.
  And after you make sure you have the above files, you should install it.
  (It makes running the game that much easier).
  MAGIGATE.DOC                                                       Page  5
  
  Installing the Game :

  Glad you asked.  Read these all the way though first, then go to it.
  (I would hate for you to read instruction #1, then go do it and get lost
  or something like that)

  STEP #1:
  
    (You've probably unzipped the program since you're reading this, but hey:)
    Unzip to a directory on your Hard drive.  Pick a subdirectory under your
    games directory or something. (c:\doors\magic would be a good one)

  STEP #2:
  
    Run Install.bat.  This will unarchive the rest of the files, and will
    run MAGICFG.EXE.  You shouldn't have to do a whole lot here.  Select
    'BBS Options' and hit enter.  Fill in SysOp name, Board name, Network
    Address, Netmail Directory (even though these two aren't used yet, they
    will be.), Select your BBS software/drop file type from the list, and
    only change the other things if you need them.  The game runs fine with
    its internal com routines, but if you're running a fossil or and extended
    fossil driver, it should be set up to run that way.  Select the com port
    if you must, or have it read it from the drop file (which is the best way 
    it will work in a multi-node system), lock your baud rate if you wish, and
    if your modem has a non-standard address or IRQ, you can change that with
    the Modify Com Port Settings.

  STEP #3:
  
    Go into Game Options and Change whatever you want.

  STEP #4:
  
    Select 'Make Batch File' from the main menu.  This will create a batch
    file that you can run as your command line from your BBS.  Create it with
    any name and copy it to your BBS directory (or leave it there if your BBS
    can execute batches in any directory).  This batch file is necessary for
    the game to run external modules.

  STEP #5:
  
    Set up the game to run as an external program in your BBS menu system and
    you are ready to go.  The command you should run should be the name of
    the batch file you created in step #4 then the node number.  I.E. the
    command line should get passed like 'MAGI 2' for node two.  Consult your
    BBS documentation on how to pass the node number in a variable.
  MAGIGATE.DOC                                                       Page  6
  
  About the 1.08 Release :

  Version 1.08 is a prettier version of 1.07 to be blunt.  There are not many
  differences between the two versions.  1.08 contains better code for handling
  stock items, a better editor in Magicfg, shops have been overhauled, and
  now, all the stock items are included in 1 big file that generates all the
  registry entries necessary for the items and writes out the scripts.  On
  top of that, mobs can be made tougher or weaker on a global level to change
  the difficulty of the game.  Some fabulous ANSI's by Sandy Chidester of
  OutWorld Arts have been added, and messageboards work a little bit better.
  I am excited as all heck about 1.08 because it is really what I wanted 1.07
  to be but didn't know it at the time.  Items RULE! *sorry* =)
  
  
  Running the Game :

  The Magic Gate practically runs itself.  It runs maintenance when the first
  player after midnight logs on.  This takes about 5-10 seconds, not very
  long at all.  I wish I could tell you more in this section, but there's
  just not a whole lot to explain:

  As of version 1.06 I have added quite a few different ways that the game
  can be modified and personalized.  I have decided that a new doc file needs
  to explain all the little ways the game can be given a personal touch.
  See CONFIG.DOC for all the information on configuring and optimizing The
  Magic Gate.

  
  Notes on the Game :
  
  The Magic Gate has a few command line switches you should know about, even
  if you don't need them.

  /Nx    (where x is 1..255) Set the node number.  This number is overridden 
         if the drop file has the node number built into it. (Good note here:
         The SRDOOR file format does not contain the node number but contains
         all the other useful information.)  If you want to run EXMODS or
         scripts available from the other realms menu, you must pass the node
         number.
  /Cx    (where x is 1..4) Set the Com port number.  This is for those souls
         whose BBS software does not include a com port number in the drop-
         file.  The default for this is Com port 0 (local mode).
  /D     Debugging mode.  This is not recommended for daily use, as it would
         generate quite a large file on a daily basis, but if you have any
         sort of problems, the DEBUG.TXT file is where you would want to start
         looking for solutions.
  /L     Play in local mode (from a DOS prompt, COM 0)
  /P<drive>:\<dir>
         Use <drive>:\<dir> as the drop-file path.  If this command is not
         present, TMG automatically uses the one in the MAGIGATE.DAT file.
  MAINT  Run TMG in the maintenance mode.  This can be done by nightly events
         run at or after midnight.  This has the same effect as a character
         logging on as the first person that day (news is updated, old chars
         are purged, interest is given, etc)
  MAGIGATE.DOC                                                       Page  7
  
  Dealing with In-Game Errors :

  Life is not perfect, computers aren't and I am definately not.  That is
  why god invented the error message.  It's his way of saying "You screwed
  something up"...  And these things can happen from time to time.  TMG has
  its ways of trapping errors, and will tell you what happened... What you
  need to know is what error it was, and what to do about it.  All errors are
  reported to the debug.txt file.  (See Page 6 for a detailed list of errors.)

  
  I get other errors :

  I don't, and neither should you, but if for some reason you do, save the
  DEBUG.TXT or DEBUG.OLD, whichever has the error code in it, and drop me a
  line explaining what you were doing at the time and what the error message
  was.

  Problem:   It won't read my drop file.
  Solution:  The game has only been tested with two different drop files,
             DOOR.SYS and DOORFILE.SR.  If you can get ahold of SRDOOR.EXE 
             (which comes with any game from The Solar Realms (BRE,SRE,FE)) you 
             should be able to convert your doorfile into a usable one.  Also 
             do this for me if you can: send me a dropfile from your BBS as 
             well as the name of the file, the type of bulletin board software 
             you are running etc so that I can fix the problem.
  
  Problem:   Running the game locks up my BBS, but I get the welcome message.
  Solution:  Perhaps your time on the BBS has run out and it hasn't kicked
             you off.  I'm trying to figure that one out too.

  Problem:   Running the game locks up my BBS, and I don't get anything.
  Solution:  Are you running a Fossil?  Did you set it up to use fossil in
             the config program?  Thats the only thing I've seen crash it with 
             no output to the user.

  Problem:   I have a multi-node BBS with different sub-directories for each
             node, where should I have it create the drop file?
  Solution:  Have your BBS software write the drop file right in the TMG
             directory.   Don't worry about it being over-written when another 
             user enters.  The drop file is read only one time and never 
             touched again.

  Problem:   When I try to go to 'Other Realms' it says : External Modules   
             not available, why is this?   
  Solution:  You are not passing the node number in the command line.  
             Running the game through a created batch file, your command
             line should read : 
               MAGI <num>  
             Where <num> is the node number the game is being run on.  Replace
             MAGI with the name of the batch file you created.
  MAGIGATE.DOC                                                       Page  8
  
  In-Game Error Codes and Solutions :
  
  Error Code :  Description :                   Solution :
  
  2             The MAGISTAT.DAT file probably  Delete MAGISTAT.DAT and run
                doesn't match the version of    MAGICFG.EXE to set up the
                the game.                       options anew.
  
  3             The PLAYERS.DAT file doesn't    As of version 1.02, TMG writes
                read the way it should or does  a backup copy of the player
                not match the version of the    file every night before maint.
                game.                           is run.  Copy PLAYERS.OLD on
                                                top of PLAYERS.DAT.
  
  4             One of the following files is   Extract the file/s from the
                corrupted: WEAPONS.DAT,         original archive.
                ARMORS.DAT, SHIELDS.DAT

  5             One of the non-game files is    See if the specified file is
                open, and needs to be accessed. open in another window and
                                                close it.  If not, try a reboot.

  6             The MAGISTAT.DAT file is open.  See #5 for MAGISTAT.DAT

  7             The MAGITEXT.DAT file is open.  See #5 for MAGITEXT.DAT

  8             The PLAYERS.DAT file is open.   See #5 for PLAYERS.DAT

  9             The WEAPONS.DAT file is open.   See #5 for WEAPONS.DAT

  10            The ARMORS.DAT file is open.    See #5 for ARMORS.DAT

  11            The SHIELDS.DAT file is open.   See #5 for SHIELDS.DAT

  12            TMG tried to access a file      Check your directory against
                that was not present.           the list of files above and
                                                extract the missing file from
                                                the original archive.

  13            The file activity has been      If you know nobody is in TMG,
                told to wait, and was not told  delete the HOLD.DAT file from
                to resume.                      the TMG directory.

  14            Player dropped their carrier.   Not really an error.

  15            Player ran out of time.         Not really an error.

  16            Player was booted out by the    Player must have been a putz:
                SysOp.                          delete immediately ;)
  
  17            Doordriver had a problem        Check your set up in MAGICFG.
                initializing.                   Chances are something is
                                                set up incorrectly.

  18            Doordriver had a bad parameter  See #17

  19            The GUILDS.DAT file has become  As of version 1.02, TMG writes
                corrupted.                      a backup copy of the guild file
                                                Copy GUILDS.OLD over GUILDS.DAT
  MAGIGATE.DOC                                                       Page  9
  
  Acknowledgemnets and Thanks :

  First, I have to thank my good friends Ken and Bill for both the use of
  their respective boards (Passport to Hades 810-853-6810 and P.C. Adventures
  810-739-3137) and the crashes they endured in the beginnning phases of
  the game, plus the ideas they've given me have helped incredibly.

  Another round of thanks goes to Sandy Chidester who provided all the ANSI
  artwork for this game.  Thanks Sandy!
  You can reach Sandy from her homepage for Outworld Arts at :
  http://www.geocities.com/SiliconValley/Heights/9359/index.html

  I also need to mention some people who contributed to this project in a
  major way without their knowledge:
   
   Scott Baker/Derrick Parkhurst for coming out with the original DoorDriver.
   Steve Lorenz and Bob Dalton for their enhancemnets to the original package.
  (Thanks guys, without your package, I probably never would have attempted
  to write an on-line game.)
   Bob Dalton again for his insight on trapping errors with his ELOG unit
  (Even though I wrote my own, I wouldn't have known how to do it without
  his unit)
   Andy Stewart even though I haven't used his InterBBS unit yet, I more than
  likely will!
   Oddly Enough, Seth Able for giving me a goal as to how far to take the
  game and taking the time to either create the `x color codes or implement
  them from someone else as I have done from his example (Think we could
  get enough authors doing it to standardize it?)

  
  For the latest version :

  I now have registered my own domain name!  be sure to update your bookmarks
  and your links!
  The fastest way to get the latest version is to check out my web site for
  The Magic Gate at

  http://www.magic-gate.com

  
  Contacting Me :
    
  Hey, send your comments, your bug reports, and your criticisms and ideas
  for the game to me.  Or, if you are interested in writing a module for the
  game, let me know, and I will do my best to assist you in doing so.

  Couple different ways to get ahold of me.  Send email to the sysop on either
  of my support BBS's

  Passport to Hades     (810)/853-6810
  P.C. Adventures       (810)/739-3137

    or
  send internet Email to
  
  joconnor@sequoianet.com
  
  Happy Gaming
  -Wyvern
