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.DAT where 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. .... ~ 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.