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 \osiris where 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 \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 \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//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 /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 /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 \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 /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. -------- The directory you extracted the SDK to. |-- -------- 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) |-- -------- Contains useful documentation |-- ----- This directory contains all the necessary headers to compile a | Descent 3 Multiplayer Mod. |-- -------- 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. |-- ------ 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). |-- -------- Contains released source code that you may want to use as | reference. |- ---- 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. |- ---- 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. |- -- 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. |- -- The source code to our Virtual Compiler for Microsoft | Visual C/C++. You can use this as a template to make | other Virtual Compilers. |- - 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 \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 \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 \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 \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 \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 \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 \src\anarchy for a base template in creating a mod). In Windows, you'll want to link with dmfc.lib located in \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 /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 /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 /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 \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 \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 \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 \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