-----------------------==================-----------------------

-=Interstellar Annihilation (ISA) IGM Developers Documentation=-

-----------------------==================-----------------------


First, thanks go to Seth Robinson (of LORD fame) for his manual 
for LORD IGMs.  I used that file as a template for this one. 
(Does that make me a thief or just resourceful?).

As of v0.994, ISA has the ability to run IGMs (In-Game Modules). 
(Called Space Ports inside ISA).

This file serves as the IGM developers' manual.

Interstellar Annihilation (ISA)                                             
Copyright (c) 1995 - 2002 Andy Stewart
ALL RIGHTS RESERVED.                                                 

Note from Andy:  You have my permission to build add-ons, editors, 
whatever you'd like for ISA.  If you create an IGM for ISA, please 
drop me a note with a copy of the IGM and I'll add it to the IGM 
section of my ISA website.  These programs/units have been written
and tested with Borland Turbo Pascal 7.0 only.  The programs have not
been thoroughly tested with Delphi as of yer.

You may charge a registration fee for your IGM if you'd like, plus 
please keep it at a reasonable amount.  Remember, as of v0.993a, 
ISA is freeware! 

Also, in any IGM you create for ISA, be sure to give some credit 
to me. ;)   

If you are going to build an ISA IGM, you !MUST! meet these specifications:

1.  It modifies NOTHING except the USER????.IN file it creates.

2.  It does NOT delete ANY ISA files (except for the USER????.IN file if it 
    pre-exists for the node the user is currently on).  ISA will handle ALL 
    file deletes, as it needs both USER????.IN/OUT upon returning from the IGM.
                                                                     
3.  It has options to install !AND! uninstall itself.  (IE: add and remove the  
    program in the DATA\ISAIGM.DAT file itself)                         
                                                                     
4.  The top line if the file_id.diz is like this:                    
    <Name and Version of your IGM> Interstellar Annihilation (ISA) IGM  
    (Decorate if you like)      

The reason I'm giving these specific instructions is because sysops 
expect simple installations, etc. and do not need to be hassled with the 
manual installation/removal of IGMs.  They have enough to deal with already.

!PLEASE! abide by these rules.  If you don't, I'll send my kids to live 
with you for a week!  Trust me, you'd DON'T want that to happen!  ;)


Color Codes:  ISA's colorcode begin with a ^\ sequence.  Here are the supported
codes:


0 - Black       1 - Blue         2 - Green         3 - Cyan
4 - Red         5 - Purple       6 - Brown         7 - Light Gray
8 - Dark Gray   9 - Light Blue   A - Light Green   B - Light Cyan
C - Light Red   D - Magenta      E - Yellow        F - White

LF - CR/LF
CL - Clear Screen

Only 0 - 7 may be used as background colors.

IE:  Blue on Black would be ^\01
     White on Blue would be ^\1F
     etc, etc, etc.


HOW DO I MAKE AN ISA IGM? 

Easy!  Your IGM will be called from STARTISA.BAT (which in turn calls
DOIGM????.BAT that ISA creates).  I suggest, if you are writing your
IGM in Pascal/Delphi that you use the A.N.G.E.L. doorkit, as this will
work seemlessly with ISA.  The sample IGM I'm including (with source)
is based on the A.N.G.E.L. kit.  Hit my page (http://www.taynik.com),
and follow the A.N.G.E.L. link.  A.N.G.E.L. will make your IGM appear 
seemless with ISA.  aISA.PAS has all the read/write routines in it 
for handling USER????.IN/OUT, EMPIRES.DAT, etc., plus structures set 
up that the information is read into.  This will make writing your IGM
a breeze!

It comes down to this:  Someone will be able to unzip your program, and
run the CFG/Installer, and it will add the required information to the
DATA\ISAIGM.DAT file.  This information is all that is needed ISA to 
automatically list your IGM as it appears to the players and run it.
The ISAIGM.DAT file is explained later in this document.

Your IGM should read in that file (text file), grabbing the first 8
lines to set up communications (if needed... not needed if using A.N.G.E.L.)
and use the remainder of the file (empire stats) to allow your IGM to do its 
thing.

For the moment, the maximum IGMs ISA will handle is 20.  I may increase this
number at a later date, but 20 is a nice round number for now.

ISA now creates EMPIRES.DAT (text file) that holds all active user names, 
empire names and whether they are under protection or not.  You may use 
this however you wish, however ISA only CREATES this file, it does NOT read 
it back in.

Again, please be considerate enough to throw a 'Uninstall' option in your
configure program that finds your line and strips it out of ISAIGM.DAT, just
in case the sysop decides not to keep it.  

I have created an IGM Setup program (IGMCFG) for your use if you so desire.  
This program is explained later in this document.  Source code is included.


(******************************************************************************)

Quick Documentation for ISAIGM.DAT.

Location:  ISA\DATA\

Information needed for IGM to display the IGM, and run the correct EXE is contained 
here.  

Note:  EXEs must be placed in the ISA\IGMS\ subdirectory under your own subdirectory.
IE:  ISA\IGMS\SPIDER\.  You need only provide your IGM's subdirectory and EXE name in 
for the 'IGM EXE Path/Name' field.  ISA will add the rest of the path.

Example:

; ISA IGMDat.  This file controls the display of IGMs within
; ISA.  
; 
; The format is IGM Name,IGM EXE Path\Name. IE:
;  
; Spider's Realm,SPIDER\SPIDER.EXE
; 
; Any lines with a semi-colon are comments and will be ignored.
 

(******************************************************************************)

Quick Documentation for EMPIRES.DAT.

Location:  ISA\DATA\

After each round of play and upon returning from an IGM,
ISA creates/updates DATA\EMPIRES.DAT with the following 
information:

Real Name        (User's Real Name)
Empire Name      (User's Empire Name)
Under Protection (Yes = under protect, No = not under protection )

Example:

; EMPIRES.DAT - Lists all active Empires in ISA.
; 3 Fields, comma delimited... format:
; Real Name,Empire Name,Under Protection
; 
AStewart,Andy's Empire,No

(******************************************************************************)

Below is information for USER????.OUT and USER????.IN.  

(******************************************************************************)

Quick Documentation for USER????.OUT. 

Location:  ISA\DATA\

???? is the node number the user is current on.  IE: USER1.OUT

USER????.OUT is created by ISA in the IGM's subdirectory before entering an IGM.  The IGM 
should then  read the file, taking the first 8 lines to set up it's communications (if needed).  

The remainder of the file contains information about the current empire that your 
IGM can modify.

Your IGM should read USER????.OUT in, and save any changes to USER????.IN

The format of the USER????.OUT follows:


User's Node Number				( Value = 0 - 255)
BBS Name					( Value = String[30] )
Sysop Name					( Value = String[20] )
Path to ISA					( Value = String[80] )
Comport used					( Value = 0 - 255 )
Baudrate					( Value = 0 - 2 billion )
Locked Baud Rate				( Value = 0 - 2 billion )
Telnet						( Value = Yes if Telnet session, No of not )
Time, in minutes, user has left on the BBS  	( Value = 0 - 255 )
User's Name			 		( Value = String[35] )
User's Empire Name				( Value = String[35] )
User's Population				( Value = 0 - 2 billion )
User's Food					( Value = 0 - 2 billion )
User's Recon Units				( Value = 0 - 2 billion )
User's Knife Troops				( Value = 0 - 2 billion )
User's Gun Troops				( Value = 0 - 2 billion )
User's Laser Troops				( Value = 0 - 2 billion )
User's Fighters					( Value = 0 - 2 billion )
User's Bombers					( Value = 0 - 2 billion )
User's Anti-Air Guns				( Value = 0 - 2 billion )
User's Anti-Air Lasers				( Value = 0 - 2 billion )
User's Ammo (Not currently used)		( Value = 0 - 2 billion )
User's Urban Planets				( Value = 0 - 2 billion )
User's Food Planets				( Value = 0 - 2 billion )
User's Industrial Planets			( Value = 0 - 2 billion )
User's Military Planets				( Value = 0 - 2 billion )
User's Tourist Planets				( Value = 0 - 2 billion )
User's Mining Planets				( Value = 0 - 2 billion )
User's Peace %					( Value = 0 - 100 )
User's Tax %					( Value = 0 - 100 )
User's Draft %					( Value = 0 - 100 )
User's Army Effectiveness %			( Value = 0 - 100 )
User's Money on Hand				( Value = 0 - 2 billion )
User's Score					( Value = 0 - 2 billion )
User's New Planets Available			( Value = 0 - 2 billion )
User's Money in Bank				( Value = 0 - 2 billion )
User's UnderGround Password			( Value = String[35] )
User's Plays Today				( Value = 0 - 255 )
User's Local Attacks Sent Today			( Value = 0 - 255 )
User's Remote Attacks Sent Today                ( Value = 0 - 255 )
User's Local Recons Sent Today			( Value = 0 - 255 )
User's Remote Recons Sent Today			( Value = 0 - 255 )
User's Money Transfers Today                    ( Value = 0 - 255 )
Sysop Defined Maximum Transfer Size             ( Value = 0 - 2 billion )

(******************************************************************************)

Quick Documentation for USER????.IN. 

Location:  ISA\DATA\

???? is the node number the user is current on.  IE: USER1.IN

USER????.IN is read by ISA from the IGM's subdirectory upon returning from an IGM.  
The IGM provides updates to the fields to be imported to the ISA record structures.

Your IGM should read USER????.OUT in, and save any changes to USER????.IN

The format of the USER????.IN file your IGM creates MUST follow the format
and must be 35 lines long.

Format:

Time, in minutes, user has left on the BBS  	( Value = 0-255 )
User's Name			 		( Value = String[35] )
User's Empire Name				( Value = String[35] )
User's Population				( Value = 0 - 2 billion )
User's Food					( Value = 0 - 2 billion )
User's Recon Units				( Value = 0 - 2 billion )
User's Knife Troops				( Value = 0 - 2 billion )
User's Gun Troops				( Value = 0 - 2 billion )
User's Laser Troops				( Value = 0 - 2 billion )
User's Fighters					( Value = 0 - 2 billion )
User's Bombers					( Value = 0 - 2 billion )
User's Anti-Air Guns				( Value = 0 - 2 billion )
User's Anti-Air Lasers				( Value = 0 - 2 billion )
User's Ammo (Not currently used)		( Value = 0 - 2 billion )
User's Urban Planets				( Value = 0 - 2 billion )
User's Food Planets				( Value = 0 - 2 billion )
User's Industrial Planets			( Value = 0 - 2 billion )
User's Military Planets				( Value = 0 - 2 billion )
User's Tourist Planets				( Value = 0 - 2 billion )
User's Mining Planets				( Value = 0 - 2 billion )
User's Peace %					( Value = 0 - 100 )
User's Tax %					( Value = 0 - 100 )
User's Draft %					( Value = 0 - 100 )
User's Army Effectiveness %			( Value = 0 - 100 )
User's Money on Hand				( Value = 0 - 2 billion )
User's Score					( Value = 0 - 2 billion )
User's New Planets Available			( Value = 0 - 2 billion )
User's Money in Bank				( Value = 0 - 2 billion )
User's UnderGround Password			( Value = String[35] )
User's Plays Today				( Value = 0 - 255 )
User's Local Attacks Sent Today			( Value = 0 - 255 )
User's Remote Attacks Sent Today                ( Value = 0 - 255 )
User's Local Recons Sent Today			( Value = 0 - 255 )
User's Remote Recons Sent Today			( Value = 0 - 255 )
User's Money Transfers Today                    ( Value = 0 - 255 )

(******************************************************************************)

Quick Documentation for IGMCFG.EXE

I wrote this program to semi-automatically install/uninstall IGMs into/out of
ISA.  I say semi-automatically because it requires one input line from the 
Sysop... the path to ISA.

As an IGM author, it is simple to set up IGMCFG to automatically install/uninstall
your IGM.  You simple edit the included IGMCFG.DAT file (textfile) to reflect your
IGM's information and you're done.  

To install an IGM with IGMCFG, the Sysop simply runs IGMCFG.EXE and gives it the path
to their ISA directory when prompted.  The program then creates the IGM's directory,
edits ISAIGM.DAT, and copies the IGM EXE to the newly created directory.  This is all
based on the information you place in IGMCFG.DAT.

To uninstall an IGM with IGMCFG, the Sysop simply runs IGMCFG /u and gives it the
path to their ISA directory when prompted.  The prgram then deletes the IGM EXE, removes
the entry from ISAIGM.DAT, and deletes the IGM's directory.

Two items to note:  
1) IGMCFG.EXE, IGMCFG.DAT, and your IGM's EXE must be in the same directory 
   (normally will be considering they should be distributed in the same archive).  
2) IGMCFG only copies the IGM's EXE.  If you have additional files, such as documentation,
   graphic screens, etc. you must edit the IGMCFG source code to copy these files.  
   (Procedure CopyNeededFiles(), cut 'n paste code to copy additional files).


IGMCFG.DAT Structure:

6 lines, anything after line 6 is not read.

Spider's Realm					( IGM Name )
Andy Stewart					( Author Name )
Copyright (c) 2001-2002 Andy Stewart		( Copyright Notice )
v0.994						( IGM Version )
SPIDER.EXE					( IGM EXE Name )
SPIDER						( IGM Directory to create/copy to )


(******************************************************************************)


Have fun!
A

-= End of document =-