  EXTERNAL.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!

  This file was written for all you code-heads out there who are interested
  in writing an external module for TMG.  This will document all the
  structures for the various things in TMG as well as giving insight into how
  to put new EXMODS into the game.  If you're a code-junkie like me, and want
  to write your own thing for everything, then this is the file you need to
  get started.


  
  Introduction:

  If the TMGSL is not powerful enough for you, or you need to do something
  totally different in your EXMOD, you should have the ammunition you need
  to get writing the code after reading this file.  You will learn the format
  of the drop file as well as the method for adding your EXMOD to the
  EXMODS.DAT file as well (which is just as useful for scripts).  Even if you
  don't plan on writing an EXMOD, this file will contain some techie stuff
  you might be interested in.

  EXTERNAL.DOC                                                      Page  2
  
  Constants in the game:

  Oh geez, there are about a million constants in this program.  Mainly
  because its so much easier to remember CLASS_MAGE then it is to remember if
  mages were 2 or 8.  Not all of these will apply 100% to each and every
  EXMOD, but some of them will be vital to understanding the values of some
  of the fields.
  
  Go figure, well, anyway, here is a list of constants that relate to file 
  names.

  CHAR_FILE='PLAYERS.DAT';         This file has all the player data
  GUILD_FILE='GUILDS.DAT';         This file has all the guilds data
  STAT_FILE='MAGISTAT.DAT';        This contains the configuration for the
                                   game, such things as costs etc.
  MENU_TEXT_FILE='MAGITEXT.DAT';   This has all the menus and unchanging text
  HOLD_FILE='HOLD.DAT';            This is used to tell any running copies not
                                   to access the disk drive temporarily
  WEAPON_FILE='WEAPONS.DAT';       This file contains data for all the weapons
  ARMOR_FILE='ARMORS.DAT';         This file contains data for all the armors
  SHIELD_FILE='SHIELDS.DAT';       This file contains data for all the shields

  GRANK_ANS_FILE='GRANK.ANS';      This file contains the ANSI guild ranks
  GRANK_ASC_FILE='GRANK.ASC';      This file contains the ASCII guild ranks
  PRANK_ANS_FILE='PRANK.ANS';      This file contains the ANSI player ranks
  PRANK_ASC_FILE='PRANK.ASC';      This file contains the ASCII player ranks

  These constants should be used for any call to open, close, read whatever
  it is you want to do to the file cause it will make your life a lot easier
  if I ever decide to change a file name ;)
  Alright, moving along, next we have all the possible flags that can affect
  the character and are stored in the main_char^.char_flags long integer.
  These determine the actions that the character has performed and determine
  which cans can still be performed if the oppurtunity arises.
  
  FLAGS_SHAMED_MASTER=1;        This flag is set if the character attacks
                                another character with the same master.
  FLAGS_MASTER_IGNORES=2;       This flag is set if the master will not do
                                anything for the character today.
  FLAGS_EXPERT_MODE=4;          Are menus shown to the player?
  FLAGS_LOUIS_THWARTED=8;       Louis has stopped the character from trying
                                to break into the inn.  All further attempts
                                are automatic failures that day.
  FLAGS_FOUND_GATE=16;          Have they found the magic gate that day?
  FLAGS_ENTERED_GATE=32;        Did they enter the gate that day?
  FLAGS_HAS_BOW=64;             Does the character have a bow and arrow?
  FLAGS_HUNTED=128;             Has a hit been put out on this character?
  FLAGS_SEEN_SHADY=256;         Have they seen Shady today?
  FLAGS_CHAR_DRUNK=512;         Did the character have one too many in the bar?
  FLAGS_MET_TRAVELLER=1024;     Have they visited the Sage today?
  FLAGS_DAILY_SECRET_1=2048;    Secret little things...
  FLAGS_DAILY_SECRET_2=4096;    Secret little things...
  FLAGS_DAILY_SECRET_3=8192;    Secret little things...
  FLAGS_DAILY_SECRET_4=16384;   Secret little things...

  EXTERNAL.DOC                                                      Page  3
  
  Default values:

  The following are only used if there is no STAT_FILE.  They are the defaults
  that will be written to the stat file.  They're just sort of here for you
  to look at.

  DEFAULT_GRACE=15;             
  DEFAULT_RESURRECT=2;
  DEFAULT_FIGHTS=25;
  DEFAULT_PFIGHTS=3;
  DEFAULT_MTRANSFER=10000;
  DEFAULT_NTRANSFER=3;
  DEFAULT_ATRANSFER=TRUE;
  DEFAULT_BANK_RATE=6.00;
  DEFAULT_HEAL_COST=4;
  DEFAULT_INN_COST=300;
  DEFAULT_DEATH_LOSE_EXP=10;
  DEFAULT_MOB_GOLD_MULT=1.20;
  DEFAULT_MOB_EXP_MULT=0.85;
  DEFAULT_MAX_GUILDS=5;

  
  Deciphering the Class variable:

  The next group of constants show the bits that correspond to each of the
  six classes as they are in the main_char^.class integer.  They are vital
  to knowing what the characters capabilities are.

  CLASS_WARRIOR     =  1;
  CLASS_MAGE        =  2;
  CLASS_THIEF       =  4;
  CLASS_HEALER      =  8;
  CLASS_RANGER      =  16;  <--+-These two were reversed in previous versions.
  CLASS_PALADIN     =  32;   <-+
  
  MASTERED_WARRIOR  =  64;
  MASTERED_MAGE     =  128;
  MASTERED_THIEF    =  256;
  MASTERED_HEALER   =  512;
  MASTERED_RANGER   =  1024;<--+-These two were reversed in previous versions.
  MASTERED_PALADIN  =  2048; <-+

  EXTERNAL.DOC                                                      Page  4
  
  Limits in TMG:

  The following constants are used in my records to limit the number of chars
  in the field, so I gave them all names that are easy to remember.

  SHORT_LENGTH=20;
  MED_LENGTH=40;
  MAX_LENGTH=86;
  DESC_LENGTH=100;
  
  The next few constants are limits on the game as far as what would unbalance
  it.  These numbers have been toyed and tinkered with from the start and they
  are just about right for most any game now.

  MAX_WEAPONS=14;               Number of different ARMORS,WEAPONS and SHIELDS
  MAX_LEVELS=20;                Total number of levels in the game.
  MAX_DAMAGE_REDUCTION=87;      How little damage can you possibly deflect?
  MAX_LUCK=30;                  Luck modifies quite a few things, and the
                                higher it goes, the easier it is to do well.
  MOB_CATCH_CHANCE=20;          {MBL} Determines at what percentage a monster
                                will attack you when you try to flee from it.
  BONUS_HIT_CHANCE=8;           {MBL} How often do you or the mob strike for
                                extra damage?
  SKILL_GAIN_LEVEL=5;           The number of percentage points you gain when
                                you raise a level in your class.
  SKILL_USAGE_NUM_LEVELS=5;     How many levels do you have to gain to earn
                                a special move usage point.
  
  {MBL} stands for "Modified by Luck" which means if you have a positive luck,
        you will succeed at the task more frequently than average.  Conversly,
        if you have a negative luck, you will succeed less frequently.

  The following denote the costs of various things that a character can pay
  to have done in the game.
  
  BOW_COST=375;
  KEY_COST=400; {This is 400*level*level (of the char w/ the higher level}
  HIT_COST=1000; {this is 1000*level*level (of the char w/ the higher level}
  STEAL_COST=500;
  
  
  EXTERNAL.DOC                                                      Page  5
  
  Structures:

  Here, take a look at them, use them, you'll need to know them to write an
  external program for TMG.  Anything in all caps is a constant you should
  be able to find in the above section.  I've grouped the pointers together
  with their associated record for easy viewing.

  ptchar=^chars;
  chars=record
    name:string[SHORT_LENGTH];          Characters Name
    real_name:string[MED_LENGTH];       Players Name or Handle
    virtual:integer;                    Their unique numerical value
    class:integer;                      Tells what class/es the character has
                                        mastered, and what is current.
    sex:integer;                        1=Male 2=Female
    attack:integer;                     The characters total attack value
    defense:integer;                    The characters total defense value
    damage_reduction:integer;           Total damage reduction.  Note, this
                                        can go over MAX_DAMAGE_REDUCTION, but
                                        the code will reduce it to max when it
                                        figures out the damage.
    charm:integer;                      The characters charm.
    shame:integer;                      How shameful the character has been
    luck:integer;                       How lucky the character is.
    guild:integer;                      guild # the character belongs to 0=none
    char_flags:longint;                 See the constants section for the XOR
                                        values to use here.
    hp:integer;                         The current hit points of the character
    mhp:integer;                        The maximum hit points of the character

  The following are no longer referenced by TMG as of version 1.07
  
    weapon:integer;                     The number of points the characters
                                        weapon adds to his attack value.
    weapon_name:string[SHORT_LENGTH];   The name of the characters weapon.
    armor:integer;                      The number of points the characters
                                        armor adds to his defense value.
    armor_name:string[SHORT_LENGTH];    The name of the characters armor.
    shield:integer;                     The number of points the characters
                                        shield adds to his damage reduction.
    shield_name:string[SHORT_LENGTH];   The name of the characters shield.
  

    gold:longint;                       Amount of gold carried
    bankgold:longint;                   Amount of gold in the bank
    gems:integer;                       Number of gems the character has
    xfers_made:integer;                 How many bank transfers the char has
                                        made that day.
    experience:longint;                 How many experience points the char.
                                        has accumulated towards levels.
    level:integer;                      Characters current level.
    skill_uses_max:integer;             Maximum # of special moves the char
                                        can do in a day.
    skill_uses_curr:integer;            The # of special moves the character
                                        has left for the day.
    skills:array[1..6] of integer;      The percentage values for each of the
                                        six classes the character has.
    1=Warrior 2=Mage 3=Thief 4=Healer 5=Ranger 6=Paladin
  EXTERNAL.DOC                                                      Page  6
  
  Structures (cont.):

    location:string[SHORT_LENGTH];      String shown when someone uses the
                                        (F)ind character command, for example
                                        "sTonio's Armory"
    time_entered:string[MED_LENGTH];    Don't even know if I've used this.
    last_played:integer;                Last game day # the character played
    died_on_day:integer;                Day # the character died on.
    home_address:string[23];            Will be used in interbbs TMG someday
    first_played:longint;               Time used for comparison between
                                        characters as to who played first etc.
    fights_left:integer;                # of creature fights left today.
    player_fights_left:integer;         # of player fights left today.
    dead:boolean;                       Is the character currently dead?
    sleep_inn:boolean;                  Is the character sleeping in the inn?
    sleep_guild:boolean;                Is the character sleeing in their
                                        guild hall?
    on_now:boolean;                     Is the character playing right now?
    next:ptchar;                        used to link em all together...
  end;

  EXTERNAL.DOC                                                      Page  7
  
  Structures (cont.):

  gamestat=record
    on_day:integer;                     What Game day # are we on?
    last_played:string;                 Used to determine whether maintenance
                                        needs to be run or not.
    date_started:string[MED_LENGTH];    Date the game was last reset.
    grace_period:integer;               How long before a character is deleted
                                        due to not playing.
    resurrection_period:integer;        How long after a character dies that
                                        he is automatically resurrected.
    reg_code_1:longint;                 Registration Code #1
    reg_code_2:longint;                 Registration Code #2
    reg_code_3:longint;                 Registration Code #3
    registered:boolean;                 Is it registered?
    registered_to:string[MED_LENGTH];   Who is it registered to?
    BBS_NAME:string[MED_LENGTH];        BBS Name being played on.
    net_address:string[23];             BBS's network address for IBBS play...
    net_mail_dir:string[MAX_LENGTH];    Directory where netmail is stored.
    creature_fights_day:integer;        # of creature fights to give each day.
    player_fights_day:integer;          # of player fights to give each day.
    allow_transfers:boolean;            Allow money transfers via bank?
    max_amount_transfer:longint;        How much can be transferred at most?
    max_num_transfers:integer;          How many transfers to allow.
    bank_rate:real;                     How much interest the character gets
                                        on the gold they have in the bank
    heal_cost:integer;                  How much it costs per level per hit 
                                        point to have it healed.
    inn_cost:integer;                   How much it costs per level to stay at
                                        the inn.
    death_lose_exp:integer;             Percentage of experience lost when you
                                        die.
    floating_gold:longint;              Amount of gold lost in the realms by
                                        dying characters.
    auto_calc:boolean;                  Auto-calculate mobs experience and gold
                                        in the creature editor?
    mob_gold_mult:real;                 Used with auto_calc as a multiplication
                                        factor for gold.
    mob_exp_mult:real;                  Used wiht auto_calc as a multiplication
                                        factor for experience.
    max_num_guilds:integer;             Maximum number of guilds to allow in
                                        the game.
    patch_level:integer;               Number of gems donated to the yet-to-
                                        be-formed city council.
  end;

  da_weapon=record                      These are the records used for
                                        WEAPONS, ARMORS and SHIELDS.
    name:string[short_length];          The items name
    attack:integer;                     The amount this item adds to its
                                        respective field.
    cost:longint;                       How much does the item cost?
  end;
  weaps=array[1..MAX_WEAPONS] of da_weapon;
  EXTERNAL.DOC                                                      Page  8
  
  Structures (cont.):

  The creature structure has changed as of version 1.06..
  the old version follows.

  ptmob=^creature;
  creature=record
    name:string[MED_LENGTH];            The name of the creature.
    level:integer;                      What level is the creature?
    attack:integer;                     The attack value of the creature.
    defense:integer;                    The defense value of the creature.
    shield:integer;                     The damage resistance of the creature.
    hp:integer;                         The max HP of the creature.
    weapon_name:string[SHORT_LENGTH];   What weapon the creature uses.  This,
                                        and armor_name really have no affect
                                        whatsoever, just makes each monster
                                        look that much more diversified.
    armor_name:string[SHORT_LENGTH];    The creatures armor name.
    death_line:string[MAX_LENGTH];      Displayed to character upon creature
                                        being defeated (not implemented yet).
    race:integer;                       This is what type of creature it is
                                        and will determine its attributes.
    gold:longint;                       Gold given to player who defeats it.
    experience:longint;                 Exp given to player who defeats it.
    verification_num:longint;           Number come up with through numerous
                                        calculations so that monsters of each
                                        level can be kept in the same range.
    next:ptmob;
  end;

  pt105mob=^creature;
  creature105=record
    name:string[MED_LENGTH];            The name of the creature.
    level:integer;                      What level is the creature?
    attack:integer;                     The attack value of the creature.
    defense:integer;                    The defense value of the creature.
    shield:integer;                     The damage resistance of the creature.
    hp:integer;                         The max HP of the creature.
    weapon_name:string[SHORT_LENGTH];   What weapon the creature uses.  This,
                                        and armor_name really have no affect
                                        whatsoever, just makes each monster
                                        look that much more diversified.
    armor_name:string[SHORT_LENGTH];    The creatures armor name.
    death_line:string[MAX_LENGTH];      Displayed to character upon creature
                                        being defeated (not implemented yet).
    gold:longint;                       Gold given to player who defeats it.
    experience:longint;                 Exp given to player who defeats it.
    verification_num:longint;           Number come up with through numerous
                                        calculations so that monsters of each
                                        level can be kept in the same range.
    next:pt105mob;
  end;

  EXTERNAL.DOC                                                      Page  9
  
  Structures (cont.):

  ptrace=^race;
  race=record
    virtual:integer;
    name:string[SHORT_LENGTH];
    size:integer;
    next:ptrace;
  end;

  ptdesc=^desc;
  desc=record
    line:string[DESC_LENGTH];
    next:ptdesc;
  end;

  ptguild=^guild;
  guild=record
    virtual:integer;                    The guild number.
    name:string[SHORT_LENGTH];          The guild name.
    leader:integer;                     The virtual number of the guild leader.
    hall:boolean;                       TRUE if they've built a hall.
    password:string[SHORT_LENGTH];      Password to get into the guild.
    credo:string[MAX_LENGTH];           Short description as to what the guild
                                        is all about.
                The following are only used if hall is true.
    gold_present:longint;               How much gold is present in the hall.
    gems_present:integer;               How many gems are present in the hall.
    guard_level:integer;                The level of the guild guardian.
    guard_name:string[SHORT_LENGTH];    The name of the guild guardian.
    guard_attack:integer;               The guard's attack value.
    guard_defense:integer;              The guard's defense value.
    guard_shield:integer;               The guard's damage resistance.
    guard_hp:integer;                   The guard's hit points.
    guard_weapon_name:string[SHORT_LENGTH];     (See mob weapon and armor name)
    guard_armor_name:string[SHORT_LENGTH];
    next:ptguild;
  end;

  ptitem=^item;
  item=record
    name:string[SHORT_LENGTH];
    attack:integer;
    maxattack:integer;
    cost:longint;
    charges:integer;
    wear_flags:integer;
    required_level:integer;
    flags:longint;
    identified:boolean;
    equipped:boolean;
    scripts_used:longint;
    scriptID:string[SHORT_LENGTH];
    next:ptitem;
  end;

  EXTERNAL.DOC                                                      Page 10
  
  Drop file:

  TMG creates a small drop file of its own that can be picked up and read by
  an EXMOD.  The name of the file will be TMG<X>.DAT where <X> is the zero
  padded node number.  The file name will always be 8 characters.
  i.e. TMG00001.DAT would be the name of the drop file for node 1.  The file
  format is pretty easy to follow, and doesn't necessarily change order, but
  I may need to throw other things in there eventually so I have been using
  keywords to tell what each line is for.  An example dropfile is below.

  NAME BASITEN                  This is the users character name.
  UFNAME JOE                    This is the users first name.
  ULNAME O'CONNOR               This is the users last name.
  COMPORT 4                     This is the com port the EXMOD should use.
  BAUDRATE 14400                This is the baud rate the modem is at. 
  LOCKBAUD 0                    This is was baud rate the port is locked at.
  ROUTINES INTERNAL             This is either INTERNAL or FOSSIL.
  DROPFILEPATH C:\MAGIC\        This is the path to the BBS's drop file.
  GRAPHICS 3                    3=ANSI, less is ASCII.
  TIMELEFT 224                  This is how much time the user has left.

  This file is read back in when the user exits the EXMOD, and if your program
  keeps track of time, it would be a good idea to write the drop file back
  before your program ends.  The only thing that will be different is the
  TIMELEFT statistic.
  
  EXTERNAL.DOC                                                      Page 11
  
  A Word about the EXMODS.DAT file:

  This file is how TMG knows that you have external modules installed into
  your game.  It is a simple file consisting of three items (but not
  necessarily only three lines).  Follow this format and have your EXMOD add
  its own three items to the end of the file.

  <Command Line>
  <Name of Module>
  <Description>
   ....
  <Description>
  ~
  The command line is what is written to the batch file for execution.  It has
  the special properties of being able to pass the node number as well with a
  variable.  If you were to enter the command line as:
  C:\MAGIC\EXMODS\HOUSE.EXE /n`*
  and this was being called from node 2, the actual command executed would be
  C:\MAGIC\EXMODS\HOUSE.EXE /n2
  I may see a need to add other things like perhaps the path to the game or
  some such thing, but for now `* is the only one.
  The name of the module is simple.  It is the name users see when they go
  to the Other Realms module.  This line can have color codes in it as well
  to spiff it up.
  The description is as many lines of text as you like to describe your module
  but keep them as short as possible.  The users can take a look at this
  description before they enter any new realm to see a general overview.
  And by all means, make sure you put a ~ on a line by itself to mark the end
  of the description.  You don't do this, and you'll be asking for trouble.

