D3 SDK Readme
Created 6/12/1999
Modified 12/2/1999

--------------------------------------------------------
Table of Contents
--------------------------------------------------------
I.     What's New?
II.    Supported Compilers
III.   Installation (Windows)
IV.    Installation (Linux)
V.     Macintosh Users Note
VI.    Directory Structure
VII.   Installing And Configuring GCC for Windows
VIII.  Using the Supplied Microsoft Virtual Compiler
IX.    Compiling A Multiplayer Mod
X.     Preparing OSIRIS Scripts for Descent 3
XI.    Using Interface Functions
XII.   Compiling A Mod With GCC
XIII.  Visual C++ 4.x and 5.x Users
XIV.   Need Help?
XV.    Quick Thanks To.

--------------------------------------------------------
What's New?
--------------------------------------------------------
Changes For 1.3:
* Some structures were improved for memory savings within Descent 3
* IDMFC_RegisterPacketReciever function was accidentally left out of previous versions, 
  is now included.

Changes For 1.0:
* Added Weapon fired event handler
* Added C interface functions so C++ is no longer required to use DMFC
* Exported command line argument functions
* Added netgame flag NF_TRACK_RANK if the mod is supposed to track kills, deaths 
  and suicides on PXO
* Removed all symbol name mangling from DMFC
* Added netgame flag NF_COOP if the game is a 'Coop' game.
* Removed dead Observer functions from gamedll_header.h
* Added functions to create and fire a weapon from object or player
* Replaced PlayerChangeShip function so it also changes the cockpit and HUD
* Exported functions and variables to work with camera views
* Exported all functions for Inventory system (works with both player inventory and 
  counter measure systems)
* Exported Object_info array, and made appropriate interface functions.

--------------------------------------------------------
Supported Compilers
--------------------------------------------------------
   Multiplayer Mods
   ----------------
   This SDK has been tested with the following compilers in Microsoft Windows 
   (*see note 1*):
      * Microsoft Visual C/C++ 5.0/6.0
      * Microsoft Visual C/C++ 4.0 (*see note 2*)
      * EGCS-1.1.2 GNU GCC for Win32 (Mingw) Version egcs-2.91.66
   This SDK has been tested with the following compilers in Linux:
      * GNU GCC Version 2.8.1

   OSIRIS/DALLAS Scripts
   ---------------------
   The tested compilers to make compatible DLLs in Microsoft Windows:
      * Microsoft Visual C/C++ 6.0 (4.0 and 5.0 not tested, but should work)
      * EGCS-1.1.2 GNU GCC for Win32 (Mingw) Version egcs-2.91.66
   The tested compilers to make compatible .so files in Linux:
      * GNU GCC Version 2.8.1

NOTE 1: It may be possible to build working mods with other Windows C++ compilers 
(such as Borland or Watcom), but it may require some fixes to the included .h and .cpp 
files.  The EGCS-1.1.2 GNU GCC for Win32 compiler was used to build a successful 
DLL in Windows, however, at the current time there is still issues with vtable referencing 
between the Microsoft VC created DMFC.DLL and the GCC created mod .DLL.  In 
order to create a mod with GCC, you must use the C callable interface functions and not 
the DMFC class. See "Using Interface Functions".

NOTE 2: While Microsoft Visual C/C++ 4.0 can be used to make multiplayer mods,  
Visual C/C++ 4.0 does not have the type bool defined, so you will have to do some 
playing around with header files to fix compiler errors.

--------------------------------------------------------
Installation (Windows)
--------------------------------------------------------
1) Unzip d3-sdk10.zip to an empty directory (make sure you keep all folders in 
   the zip intact). E.g. C:\D3-SDK\
2) If you are using D3Edit to create levels, and would like to create level scripts, 
   then in D3Edit, go to File|Settings (from the menu).  Configure the scripts 
   directory to point to <base-dir>\osiris where <base-dir> is the directory you 
   extracted d3-sdk.zip to.  You will also need to configure your Virtual 
   Compiler, if you own Microsoft Visual C++, you can use the supplied 
   VirtualMS Virtual Compiler (see instructions below).  If you don't have 
   Microsoft Visual C++, but would still like to create scripts (level scripts or 
   game scripts), then follow the directions outlined below on Installing and 
   Configuring GCC for Windows.  If you own a compiler capable of creating 
   Windows 32-bit DLLs you can either create your own Virtual Compiler (or 
   download one someone else has created, if one exists).  See 
   <base-dir>\doc\D3 Virtual Compiler Spec.doc for more information on 
   Virtual Compilers, and technical specifications to create one.
3) If you configured D3Edit in step 2, be aware that all scripts you create via 
   Dallas will be saved/loaded from your <base-dir>\osiris directory.  Descent 3 
   will not be able to load scripts from that directory, so you will have to package 
   the scripts up in order to play your scripts.  See the section below on 
   Preparing Scripts For Descent 3.

--------------------------------------------------------
Installation (Linux)
--------------------------------------------------------
1) gunzip/untar the d3-sdk.1.0.tar.gz to an empty directory (like 
   /home/<username>/d3-sdk/) with the command "tar -zxvf d3-sdk.1.0.tar.gz".
2) If you plan on building scripts for Descent 3, you can use the script in 
   <base-dir>/bin/build_script for convenience.   Just make sure that the 
   build_script is in your PATH so your shell can find it.  Note:  Scripts created 
   via Dallas call some Windows API functions, which are not available in 
   Linux.  In your <base-dir>/osiris directory are a couple useful files 
   (linux_lib.cpp and linux_lib.h) which contain the missing API function calls.  
   Compile these with the script for a successful build.  The build_script in 
   <base-dir>\bin automatically includes them during build.
3) If you have installed the Descent 3 Linux Dedicated Server, you can skip this 
   part.  If you haven't installed the Linux version of the Dedicated Server, then 
   you will need to copy the dmfc.so.1.0 from your <base-dir>/lib to /usr/lib (it 
   is VERY important that it goes in /usr/lib).  Next create a symbolic link to it, 
   called dmfc.so ("ln -s /usr/lib/dmfc.so.1.0 /usr/lib/dmfc.so"). Run ldconfig to 
   register them with Linux.

--------------------------------------------------------
Note for Macintosh Users
--------------------------------------------------------
As of this release, there is no available D3-SDK for the Macintosh platform.

--------------------------------------------------------
Directory Structure
--------------------------------------------------------
The following is a description of the directory structure found after extracting the 
D3-SDK.

<base-dir> -------- The directory you extracted the SDK to.
|-- <bin>  -------- Contains some pre-compiled executables which may be useful.  
|                   This includes virtualms.exe (Microsoft Visual C/C++ Virtual 
|                   Compiler for D3Edit), virtualgcc.exe (EGCS 1.1.2 GNU GCC 
|                   [Mingw] Virtual Compiler for D3Edit), and build_script (a useful 
|                   script for building OSIRIS scripts in Linux via gcc)
|-- <doc>  -------- Contains useful documentation
|-- <include> ----- This directory contains all the necessary headers to compile a 
|                   Descent 3 Multiplayer Mod.
|-- <lib>  -------- This directory contains dmfc.lib, necessary to build a Descent 3 
|                   Multiplayer Mod for Windows.  It also contains dmfc.so.1.0 for 
|                   Linux, if you haven't installed the Linux Descent 3 Dedicated 
|                   Server, see Installation (Linux) on how to install it for use.
|-- <osiris> ------ This directory contains any necessary files to build OSIRIS scripts
|                   for your levels.  Some of the files in there are needed for DALLAS 
|                   (in D3Edit).
|-- <src>  -------- Contains released source code that you may want to use as 
      |             reference.
      |- <anarchy> ---- The source code for Outrage Entertainment's Anarchy 
      |                 Multiplayer Mod.  Which includes the project file for 
      |                 Microsoft Visual C/C++ 6.0, and a Makefile for Linux 
      |                 compilation.  This is a relatively simple mod and can be 
      |                 used as a base template.
      |- <entropy> ---- The source code for Outrage Entertainment's Entropy 
      |                 Multiplayer Mod.  Which includes the project file for 
      |                 Microsoft Visual C/C++ 6.0, and a Makefile for Linux 
      |                 compilation.  This is a complicated mod and is 
      |                 recommended for advanced users.
      |- <anarchy-c> -- The source code for Outrage Entertainment's Anarchy 
      |                 Multiplayer Mod.  Which includes the project file for 
      |                 Microsoft Visual C/C++ 6.0, and a Makefile for Linux 
      |                 compilation.  This version uses the C callable interface 
      |                 functions to interact with DMFC.
      |- <virtualms> -- The source code to our Virtual Compiler for Microsoft 
      |                 Visual C/C++.  You can use this as a template to make 
      |                 other Virtual Compilers.
      |- <virtualgcc> - The source code to our EGCS-1.1.2 GNU GCC [Mingw] 
                        Virtual Compiler layer.  You can use this as a template to 
                        make other Virtual Compilers.

--------------------------------------------------------
Installing and Configuring GCC for Windows
--------------------------------------------------------
     Check out http://www.xraylith.wisc.edu/~khan/software/gnu-win32/ for more 
information on EGCS-1.1.2 GNU GCC for Windows.
     To download, go to ftp://ftp.xraylith.wisc.edu/pub/khan/gnu-win32/mingw32/egcs-1.1.2/ 
(see the file INSTALL for more thorough directions).  Download Egcs-1.1.2-mingw32.zip.  
Unzip the file to C:\EGCS-1.1.2\ (preserving the sub-directories).  After doing this, edit 
your PATH to include the C:\EGCS-1.1.2\BIN directory.

Win9X users:
-----------
    edit/add to your C:\autoexec.bat 
    SET PATH=C:\EGCS-1.1.2\BIN;%PATH%
WinNT users:
------------
    You'll have to edit the PATH environment variable in your 
    Control Panel->System->Environment tab 
    To include C:\EGCS-1.1.2\BIN in it.

After you do this, all that's left is to reboot.  To test the installation, bring up a Command 
Prompt and type "gcc -v", if it prints out the version of the GCC compiler, then it is 
installed.  

Once it is setup correctly, you can use the Virtual Compiler for GCC.  You'll have to 
configure D3Edit for the virtualgcc Virtual Compiler. To do this, open D3Edit and go 
into the File menu and select Settings.  In here you can set what kind of settings you want 
for your Virtual Compiler.  But you need to choose your Virtual Compiler first.  Click on 
the "..." next to the "Virtual Compiler Path: " edit box, to browse for your Virtual 
Compiler.  Maneuver to the <base-dir>\bin of your D3-SDK installation.  Choose the 
virtualgcc.exe file.  You also will need to find your script directory, which will be located 
in  <base-dir>\osiris.  That should be all there is to setting up.  Look at the 
documentation/help with D3Edit to see how to create a script and test out the compiler 
installation.

--------------------------------------------------------
Using the Supplied Microsoft Virtual Compiler
--------------------------------------------------------
	Included in this release is a Virtual Compiler for Microsoft Visual C/C++.  
VirtualMS has been tested with Microsoft Visual C/C++ 6.0, but should work for some 
earlier versions without any problems.  If you own Microsoft Visual C/C++ and would 
like to use it to build your OSIRIS scripts using the supplied Virtual Compiler, these are 
the steps to set it up and use it in D3Edit.
	When you installed Microsoft Visual C/C++ it created a file called vcvars32.bat, 
and placed it in the Bin subdirectory of your Microsoft Visual C/C++ installation 
directory.  You need to have certain environment variables set in order for the compiler to 
know where to look for certain files.  The easiest way to ensure that they are setup 
correctly is to call vcvars32.bat during startup.  In Windows 9X you can call it from your 
autoexec.bat file during boot.  So if it called correctly, you should see the message:
"Setting environment for using Microsoft Visual C++ tools." or something similar 
during boot.
	Next you'll have to configure D3Edit. To do this, open D3Edit and go into the 
File menu and select Settings.  In here you can set what kind of settings you want for 
your Virtual Compiler.  But you need to choose your Virtual Compiler first.  Click on the 
"..." next to the "Virtual Compiler Path: " edit box, to browse for your Virtual Compiler.  
Maneuver to the <base-dir>\bin of your D3-SDK installation.  Choose the virtualms.exe 
file.  You also will need to find your script directory, which will be located in 
<base-dir>\osiris.  That should be all there is to setting up.  Look at the 
documentation/help with D3Edit to see how to create a script and test out the compiler 
installation.

--------------------------------------------------------
Compiling A Multiplayer Mod
--------------------------------------------------------
	For the most part, Descent 3 multiplayer modifications can contain nearly 
anything.  However, there are some requirements that all modifications must include. 

* In order for Descent 3 to find a mod to use during gameplay, the 
  compiled mod must be located in your <Descent 3 Base 
  Directory>\netgames directory, with a .d3m extension
* The .d3m file can be either a straight .DLL (in the Windows 
  environment) or a .so (in the Linux environment) with a .d3m extension, or it 
  can be a hog file.  If it is a .DLL/.so then any files (graphics/sounds/table files) 
  referenced in the mod must be somewhere where Descent 3 can find them.  If 
  these files are not in the d3.hog/extra.hog then they can be located in the base 
  Descent 3 directory, or in one of the sub-directories of 
  <Descent 3 Base Directory>\custom. The other option is to pack your mod 
  into a hog file.  You must make sure your mod is the same name as the hog 
  file (minus the filename extension).  You can put just the Window's DLL or 
  both the Windows's DLL version of your mod, and the Linux so file.  You can 
  place any files that your mod maybe dependent on in the hog file also.  Make 
  sure the hog file's filename extension is d3m.  For example, you have your 
  multiplayer mod called "mymod".  The compiled mod for Windows would be 
  mymod.dll, and for Linux would be mymod.so.  Place mymod.dll and/or 
  mymod.so into a hog file (using available utilities), named mymod.d3m.  
  Place mymod.d3m in your netgames subdirectory of where you installed 
  Descent 3.  If all goes well, your mod should now be available when you start 
  a multiplayer game.
* While it is possible (albeit nearly impossible) to make a Descent 3 
  mod without using DMFC (Descent Multiplayer Foundation Class), it is 
  highly recommended that you use DMFC in creating your mod, as it 
  performs many useful functions and event handling behind the scenes.  It also 
  contains a number of useful API functions in which you can use while making 
  your mod.
* To link with DMFC, include "dmfc.h", "idmfc.h" and 
  "gamedll_header.h" in your source code.  See the source code to Anarchy 
  (located in <base-dir>\src\anarchy for a base template in creating a mod).  In 
  Windows, you'll want to link with dmfc.lib located in <base-dir>\lib.  In 
  Linux, you'll want to link with /usr/lib/dmfc.so which is installed when you 
  install Descent 3 in Linux or followed the directions in Installation (Linux).  If 
  you did not install Descent 3 in Linux, then copy the file located in <base-
  dir>/lib/dmfc.so.1.0 (using cp) to your /usr/lib directory.  Make a symbolic 
  link from that file to /usr/lib/dmfc.so by executing "ln -s /usr/lib/dmfc.so.1.0 
  /usr/lib/dmfc.so" and run ldconfig to register them with Linux.  It is 
  necessary that you link with the files from /usr/lib/dmfc.so and no other 
  directory/file.
* In order for Descent 3 to load a multiplayer mod, nine functions must  
  be exported from the d3m.  Descent 3 binds with these functions, and uses 
  them to interface with the mod.  These functions are:
     void DLLGameInit (int *api_func,ubyte *all_ok,int num_teams_to_use);
     void DLLGameCall (int eventnum,dllinfo *data);
     void DLLGameClose ();
     void DLLGetGameInfo (tDLLOptions *options);
     int GetGOScriptID(char *name,ubyte isdoor);
     void *CreateInstance(int id);
     void DestroyInstance(int id,void *ptr);
     short CallInstanceEvent(int id,void *ptr,int event,tOSIRISEventInfo *data);
     int SaveRestoreState( void *file_ptr, ubyte saving_state );

It is imperative that these functions use the stdcall calling convention, consult 
your compilers documentation to see how to do this (or just look at the supplied 
source code).  You may recognize five of these functions from OSIRIS (Outrage 
Systems Intelligence and Real-time Instruction Scripting system).  That is because 
multiplayer mods can include OSIRIS scripts.  These functions must be exported 
with the following names (respectfully):
    _DLLGameInit@12 or DLLGameInit
    _DLLGameCall@8 or DLLGameCall
    _DLLGameClose@0 or DLLGameClose
    _DLLGetGameInfo@4 or DLLGetGameInfo
    _GetGOScriptID@8 or GetGOScriptID
    _CreateInstance@4 or CreateInstance
    _DestroyInstance@8 or DestroyInstance
    _CallInstanceEvent@16 or CallInstanceEvent
    _SaveRestoreState@8 or SaveRestoreState

--------------------------------------------------------
Preparing OSIRIS Scripts for Descent 3
--------------------------------------------------------
	In order for Descent 3 to find your OSIRIS (or DALLAS created) script to load it, 
you have a couple options.  Descent 3 will look only in certain files to find your script.  
These include d3.hog, extra.hog and your mission's mn3 file.  Obviously you should 
never put your scripts in d3.hog or extra.hog, as you won't be able to distribute your 
script while they are in there (it will also cause problems if you try to run an upgrade 
patch to Descent 3, when it tries to patch those files).  So your only solution is to place 
them in your mission's mn3 file.  When you create a mn3 for your level(s), along with the 
.d3l files, you'll also want to put your scripts in the mn3 (which is a hog file, with a .mn3 
file extension).  You'll want to take the .dll file created in your <base-dir>/osiris 
directory (and/or in the case of Linux, the .so file) and place that inside the mn3 file.  If it 
is a script created via DALLAS in D3Edit, then you'll also want to add the .msg file 
along with the compiled script(s).  You may place both the .so and the .dll files in the 
mn3, this will make your script available on both Windows and Linux platforms.  If you 
have any other files which you reference in your scripts/levels, you'll want to place them 
in the mn3 also (this includes a mission tablefile and it's related files).  When your mn3 is 
created, place it in your <Descent 3 Base Directory>/missions subdirectory, and load up 
Descent 3 to test out your mission/scripts.  You may find it wise to create some 
scripts/batch files to automate this process to make it easier/faster to build and test your 
levels/missions.

--------------------------------------------------------
Using Interface Functions
--------------------------------------------------------
	Starting with release 1.0 (this release), every DMFC class (this includes DMFC, 
DmfcStats and MenuItem classes) has each member function wrapped in a C callable 
function.  This makes loosens the requirement for a C++ compiler.  If a compiler has 
problems creating a DLL that calls virtual functions in a Microsoft created DLL (like 
GCC), you can now use the C interface functions to get around this limitation.  See 
<base-dir>\src\anarchy-c for an example of how to use the C interface functions.

--------------------------------------------------------
Compiling A Mod with GCC for Windows
--------------------------------------------------------
Currently vtable referencing doesn't work with the EGCS GCC for Windows.  So 
you must make sure you use the C-Interface functions instead of the DMFC class 
members. See the source code in <base-dir>\src\anarchy-c for an example.  Included are 
the steps to compile a mod successfully using the EGCS compiler (Mingw):

1) Compile the object files. 
      gcc -c -I. -I..\..\include [-g] -o file.o -c file.cpp
   Use the -g parameter if you want debugging information.  Replace file.cpp 
   and file.o with the correct source file for your mod.  Repeat this step for each 
   source file you have.
2) Linking the file.
      dllwrap -mwindows -o file.dll ..\..\lib\dllinit.o file.o [...] ..\..\lib\dmfc.a -def ..\..\lib\mod.def
   Replace file.dll with the name of the mod DLL you are creating.  Replace 
   file.o (and [...] if you have more than one source file) with the object files 
   created by step 1.
3) Creating dmfc.a
   You may need to create lib\dmfc.a if it does not exist.  To create it, change 
   directory into you <base-dir>\lib directory and execute the following.
      dlltool --dllname dmfc.dll --def dmfc.def -output-lib dmfc.a


--------------------------------------------------------
Visual C++ 4.x and 5.x Users
--------------------------------------------------------
   In order to build multiplayer mods with Visual C++ 4.x/5.x you will need to generate a
compatible dmfc.lib import library.  To do so, execute the following command on the 
command line (you may have to make sure the the lib.exe tool included with Visual C++ is 
in your path):

	lib /DEF:dmfc.def /NAME:dmfc.dll /OUT:dmfc.lib

   Execute this in the <base-dir>\lib directory of the D3-SDK.

--------------------------------------------------------
Need Help?
--------------------------------------------------------
     Check out http://www.warpcore.org/~d3sdk/ for some help with the D3-SDK.  You'll find 
tutorials, articles and FAQs to help you solve any problems you may have.
     Also check the forums located at http://d3edit.tricordnet.com/.
     As a last resort, if you are still unable to get any assistance, you can email 
d3mod@outrage.com where I'll try my best to answer your question for you as soon as 
possible.

--------------------------------------------------------
Quick Thanks To.
--------------------------------------------------------
Scott `fathom' Roberts
Matt `donut' Mueller 
Chris `Gwar' Ledwith
Victor `Sekmu' Rachels 
