                 The unofficial Half-Life MOD FAQ (version 1.0)
                                   by botman


1. What is the purpose of this FAQ?
   This FAQ was written to answer some common questions about creating MODs
   for the game Half-Life (developed by Valve Software and distributed by
   Sierra Studios).  Information contained in this FAQ is in NO WAY endorsed
   by or supported by Valve Software, Sierra Studios, or any other company
   affiliated with the game Half-Life.  Valve is a trademark of Valve LCC.
   Sierra is a trademark of Sierra On-Line Inc.

   This FAQ WILL NOT tell you how to write code.  This FAQ WILL NOT tell you
   what each class or variable or function in the SDK does.  This FAQ WILL
   NOT tell you how to create models, sprites, or cool effects in the game.

   This FAQ will tell you what you need to know to set up a MOD.  This FAQ
   also contains a list of common errors, a list of Internet resources for
   asking coding questions, and a list of tutorials, tools, and other freely
   available resources found on the Internet.

2. What is a Half-Life MOD?

   A Half-Life MOD is a modification that someone has made to the single
   player or multiplayer version of the game Half-Life.  These MODs usually
   incorporate new weapons, new levels (maps), and/or new methods or rules
   for playing the game.  Some MODs are single player only, which means that
   you play against monsters (like in the original Half-Life game) using new
   weapons, new levels and/or new monsters.  Other MODs are multiplayer
   (deathmatch) only MODs, where you play against other human players
   connected through the Internet, or on a Local Area Network (LAN).  Some
   MODs support both single player and multiplayer.

3. What are some of the MODs that are better known?

   One of the MODs that was included with an update to Half-Life is Team
   Fortress Classic.  Team Fortress Classic (TFC) was the first MOD for
   Half-Life that allowed players to form teams and work together to defeat
   the opposing team.  Capture The Flag is one of the variations that Team
   Fortress Classic supports.  Counter Strike is another well-known MOD that
   allows players to work as a team.  In Counter Strike you are on one of
   two teams, the terrorists, or the counter-terrorists.  The terrorists
   have seized a group of scientists and the counter-terrorists try to
   rescue the scientists.  Members of each team try to kill players on the
   other team without getting killed themselves.  Action Half-Life is
   another MOD available that creates a more realistic set of game play
   rules.  In Action Half-Life, when a player gets shot, they run, walk,
   or limp at a slower pace than players who aren't injured.  Each of these
   MODs have new weapons that are not available in the original version of
   Half-Life.

4. What do you need to build a Single Player MOD?

   To build a single player MOD you will need to obtain the Professional SDK
   from Valve LCC.  The Professional SDK comes on a CD and contains all the
   source code used to create the DLL used by the original game.  The Pro
   SDK contains all of the Artificial Intelligence (AI) code used for
   monsters, human military, and scientists found in the original game.  To
   obtain the Pro SDK you will need to sign a Non-Disclosure Agreement (NDA)
   with Valve LCC which states that you will not reveal the contents of the
   CD and you will not create a commercial product without first contacting
   Valve about distributing it.  The Pro SDK is available free of charge
   (except for the stamp to mail the NDA).  You can obtain more information
   about the Professional SDK by visiting the web site at...

   http://www.valvesoftware.com/hlsdk.htm

   Here's an example of how to fill out the NDA...

   http://www.planethalflife.com/wavelength/sdk_nda.html

   You will also need a C++ compiler that is capable of building DLL files
   that are compatible with Microsoft Visual C++.  The SDK contains Microsoft
   Visual C++ Workspace files that can be used to build the DLL files,
   providing you have Microsoft Visual C++ version 5.0 or 6.0.  You can also
   use a freely available C++ compiler environment called MingW32 to build
   the DLL files.  Information on using MingW32 is available at...

   http://planethalflife.com/botman/MingW32.shtml

5. What do you need to build a Multiplayer (DeathMatch) MOD?

   To build a multiplayer MOD you will only need the Standard SDK, which is
   available on many Half-Life related web sites.  The Standard SDK does NOT
   contain the monster/grunt/scientist AI code found in the Pro SDK, so you
   will not be able to have monsters or grunts or scientists in your MOD
   unless you code the AI routines yourself.  The Standard SDK is available
   in at least 2 different forms.  One contains code for creating maps,
   player models, DLL files, sprites, textures, and weapon models.  This
   version of the Standard SDK is about 14 Megabytes in a Zip file.  Another
   version of the SDK only contains the source code used to build DLLs.
   This version is about 714 K bytes in a Zip file.  The larger of the two
   of these contains a Microsoft Word document called "How to make a mod"
   that contains many details about building a MOD for Half-Life.  You can
   download the SDK from the following web sites:

   http://www.fileplanet.com/  (search for HLStandardSDK.zip)

   http://www.planethalflife.com/dl/dl.asp?planethalflife/wavelength/StandardSD
   KSource.zip

   http://www.planethalflife.com/dl/dl.asp?planethalflife/hlprogramming/standar
   dsdksource.zip 

   You will also need a C++ compiler that is capable of building DLL files
   that are compatible with Microsoft Visual C++.  The SDK contains Microsoft
   Visual C++ Workspace files that can be used to build the DLL files,
   providing you have Microsoft Visual C++ version 5.0 or 6.0.  You can also
   use a freely available C++ compiler environment called MingW32 to build
   the DLL files.  Information on using MingW32 is available at...

   http://planethalflife.com/botman/MingW32.shtml

6. What do I need to know before starting to create a Half-Life MOD?

   The Half-Life SDK is written in a computer programming language called
   C++.  You need to have a fairly good understanding of how to write
   software using the C++ programming language.  If you are unfamiliar with
   C++, you can start by purchasing some books on C++ programming to become
   more familiar with the C++ programming language.

   You need to know how to use the C++ compiler you will be using to build
   the DLL files.  This involves knowing how to add new modules to the DLL
   or remove existing modules from the DLL.  You need to understand how to
   interpret the error messages given by your compiler when compiling the
   C++ source files that make up the DLL.  You need to know how to modify
   compiler options, if necessary, to build the DLLs.

   You need to learn how the code in the Half-Life SDK operates.  This
   usually involves looking at existing code in the SDK to learn how things
   fit together.  Again, you NEED to understand C++ to understand the SDK.
   The SDK relies heavily on C++ classes and inheritance.  There are some
   comments sprinkled about in the SDK source code and the classes and
   functions in the SDK are fairly well written and fairly well structured.

   One way to become more familiar with what types of modifications can be
   done using the SDK is to take a look at the various Half-Life coding
   tutorials available on the Internet.  These tutorials show examples of
   how to change weapons, ammo, sprites, and other effects in the game.

   The last thing that you need to have before beginning a Half-Life MOD is
   a well thought out design of what you want the MOD to be.  Above all
   else, make sure that the MOD will be something that is fun to play, over
   and over and over again.  Make sure that the MOD will be something that
   other people, besides yourself, will want to play.  Many people begin a
   MOD with just a vague idea of having "really cool weapons and stuff", and
   usually don't get very far.  The MOD should have some sort of overall
   theme.  A futuristic space station setting, the old west, world war II,
   or a prehistoric caveman setting, are examples of a theme for a MOD.
   The weapons, textures, models, and gameplay should all tie in with this
   theme.  Don't create an old west MOD with lazer blasters and light sabers.
   Make sure everything in the MOD ties together.

7. What are the steps necessary to have Half-Life load a MOD?

   Each MOD goes into a separate directory within the Half-Life directory.
   When you create a MOD, you must use a unique subdirectory name which will
   contain all of the files that will be used for that MOD.  The directory
   structure of your MOD will mirror the directory structure of the
   C:\SIERRA\Half-Life\valve subdirectory.

   For example, if the name of your MOD is "Blastzone", you would create the
   directory C:\SIERRA\Half-Life\Blastzone.  If the MOD contains new maps,
   the maps would be in C:\SIERRA\Half-Life\Blastzone\maps.  New models
   would be in C:\SIERRA\Half-Life\Blastzone\models\player, and so on.

   In the Blastzone directory, you must create a text file called
   "liblist.gam".  The liblist.gam file contains options about the MOD that
   tells the name of the game, URL information for the web site where the
   MOD can be found on the Internet, the version number, the size, whether
   the MOD is single player or multiplayer, and other options.  Read the
   "How to make a mod" document for details on these liblist.gam options.

   Whether you are building a single player or multiplayer MOD, you will
   need to create a dlls directory (note the "s" in dlls) in your MOD
   directory.  For the Blastzone MOD this would be C:\SIERRA\Half-Life\
   Blastzone\dlls.  In the dlls directory you would put the hl.dll or
   mp.dll file (for single player or multiplayer respectively) that you
   build from the SDK for your specific MOD.  In the liblist.gam file you
   have a "gamedll" option.  This "gamedll" option should be set to
   "dlls\hl.dll" (for single player) or "dlls\mp.dll" (for multiplayer).
   Make SURE that the gamedll option has the correct directory and filename,
   for example "dlls\mp.dll" and NOT "dll\mp.dll" (without the 's').

   If you are customizing the HUD display (adding weapon slots, changing HUD
   colors, etc.), you will need to create a "cl_dlls" folder (note the "s")
   in your MOD directory (C:\SIERRA\Half-Life\Blastzone\cl_dlls for example).
   The cl_dlls folder will contain the client.dll file, which is used for
   client side modifications to the HUD.  In the liblist.gam file, you will
   need to set the "cldll" option to "1" to indicate that the MOD requires a
   custom client.dll file.

8. How do I activate my MOD in the game?

   To cause Half-Life to activate your MOD, you can start the game using the
   command line "hl.exe -game Blastzone", or you can select "Custom game" in
   the main menu.  In the Custom game menu, click on the name of your MOD
   from the list of MODs and click on "Activate".  Click on "Done" and then
   select "New game" or "Multiplayer", depending on whether your MOD is
   single player or multiplayer.

9. What if my version of Half-Life doesn't have the "Custom game" option?

   You will need to use "Update" to download the latest version of
   Half-Life.  Currently the latest version available from Sierra Studios
   is version 1.0.1.3.  You can also download the update file from the
   following web site...

   http://www.fileplanet.com/   (click on the Half-Life link)

10. How do I build the mp.dll file for multiplayer MODs?

   Download the SDK zip file from one of the above sources and unzip it to a
   directory of your choice.  If you are using Microsoft Visual C++, click
   on "File" then "Open Workspace" and browse to the directory where you
   unzipped the SDK.  Browse to the "dlls" folder and select the mp.dsw
   workspace file.  Click on "Open" to open the workspace.  Click on "Build"
   then "Build mp.dll" to build all the object files and the mp.dll file.
   When the mp.dll file is built, the last step of the build process will
   copy the mp.dll file to "\half-life\mp\dlls" (which probably doesn't exist
   on your machine).  To change this so that Microsoft Visual C++ copies the
   mp.dll file to your MOD directory, click on "Project", then "Settings"
   and scroll to the "Custom Build" tab.  Change the description to something
   like "Copying to dlls folder.".  Change the "Build commands" to "copy
   $(TargetPath) C:\SIERRA\Half-Life\Blastzone\dlls" (replacing Blastzone
   with the name of your MOD directory) and click on "OK".  If you click on
   "Build" then "Build mp.dll" again, it should copy the mp.dll to your MOD's
   dlls directory.

11. How do I build the client.dll file?

   If you are using Microsoft Visual C++, click on "File" then "Open
   Workspace" and browse to the directory where you unzipped the SDK.  Browse
   to the "cl_dll" folder and select the cl_dll.dsw workspace file.  Click on
   "Open" to open the workspace.  If this is the first time you have built
   the client.dll file, you will need to change one of the C++ compiler
   options.  Click on "Project" then "Settings" and select the "C/C++" tab.
   Click in the "Project Options" field and scroll the cursor ALL THE WAY
   to the end.  Add the following option "/Ob0" (without the quotes, that's
   a forward slash, a Capitol O, a lowercase b, and a zero, with no spaces).
   This will turn off Inline Function Expansion, which causes problems with
   the DLL if left enabled.  Click on "OK" to save these changes.  Click on
   "Build" then "Build client.dll" to build all the object files and the
   client.dll file.  When the client.dll file is built, the last step of the
   build process will copy the client.dll file to "\half-life\mp\cl_dlls"
   (which probably doesn't exist on your machine).  To change this so that
   Microsoft Visual C++ copies the client.dll file to your MOD directory,
   click on "Project", then "Settings" and scroll to the "Custom Build" tab.
   Change the description to something like "Copying to cl_dlls folder.".
   Change the "Build commands" to "copy $(TargetPath) C:\SIERRA\Half-Life\
   Blastzone\cl_dlls" (replacing Blastzone with the name of your MOD
   directory) and click on "OK".  If you click on "Build" then "Build
   client.dll" again, it should copy the client.dll to your MOD's cl_dlls
   directory.

12. What are some Internet sites with Half-Life coding tutorials?

   http://www.planethalflife.com/wavelength/
   http://www.planethalflife.com/fixxxer/
   http://www.planethalflife.com/hlprogramming/
   http://hlpp.valveworld.com/
   http://www.balfourroad.demon.co.uk/

13. What are some Internet sites with forums (bulletin boards) on Half-Life 
coding?
 
   http://dynamic.gamespy.com/~wavelength/ubb/Ultimate.cgi
   http://forums.gamedesign.net/forums/wwwthreads.pl
   http://dynamic.gamespy.com/~hlprogramming/ultimatebb/Ultimate.cgi
   http://www.telefragged.com/message_boards/hlpp/

14. What are some Internet sites with tools to aid in Half-Life coding, modeling 
and mapping?

   http://www.planetquake.com/quark/
   http://www.swissquake.ch/chumbalum-soft/
   http://www.fileplanet.com/   (click on the Half-Life link)
   http://www.planethalflife.com/wavelength/files.htm
   http://www.planethalflife.com/hlprogramming/files.htm

15. What are some Internet sites with general information about Half-Life 
(mapping tutorials, modeling tutorials, cheat codes, etc.)?

   http://www.planethalflife.com/
   http://www.halflife.net/
   http://www.planethalflife.com/coldfusion/
   http://www.planethalflife.com/modcentral/
   http://halflife.pcgame.com/
   http://www.planethalflife.com/prefablab/
   http://www.karljones.com/halflife/
   http://www.planethalflife.com/mach3/
   http://www.planethalflife.com/workshop/
   http://halflife.gamedesign.net/
   http://www.planethalflife.com/commands/
   http://www.halflife.net/hec/
   http://www.planethalflife.com/whenitsdone/
   http://www.gamedesign.net/
   http://www.halflife.org/

16. How do I find other people interesting in working on my MOD?

   Most of the Half-Life forum and bulletin board sites listed above have a
   "Help Wanted/Help Offered" section where you can post information about
   your MOD and find out if there are any other developers that would be
   willing to help you create your MOD.

17. How do I test my MOD?

   The easiest way to test a MOD is to use a LAN with 2 or more computers
   networked together running the same Half-Life MOD.  If you don't have
   access to 2 or more computers on a LAN, you will probably have to test
   using an Internet connection.  In many of the Half-Life forums or
   bulletin boards, you can ask people to help you test your MOD.  When
   testing a MOD, one computer would be set up as the server (i.e. use
   "Create game"), and the other computer(s) would connect to that server.
   You may have to determine your IP address if you are using a dial-up
   Internet account.  You can find out your IP address using a program
   called "winipcfg.exe" found in the Windows directory.

18. How do I promote and distribute my MOD?

   Most MOD developers start by obtaining a free web site and creating a web
   page with information about their MOD.  You can make the MOD available
   for download from the web site.  Once the MOD becomes popular, you may
   get invited to have your site hosted on one of the more popular Half-Life
   web sites (www.planethalflife.com, www.halflife.net, etc.).  Once the MOD
   becomes popular and well known, many other Half-Life news sites will
   begin posting news items about the latest release of your MOD.

19. How do I edit Sprites (like weapons crosshairs) used in Half-Life?

   http://www.planethalflife.com/wavelength/2dart/tutorials/sprites.html
   http://www.planethalflife.com/wavelength/2dart/articles/advsprites.html
   http://www.planethalflife.com/wavelength/2dart/tutorials/SpriteTutorial.html

20. How do I create or edit Textures in Half-Life?

   http://www.planethalflife.com/wavelength/2dart/tutorials/TextureTutorial.html

21. How do I change the menus in Half-Life used to start a game?

   http://www.planethalflife.com/wavelength/2dart/tutorials/MenuTutorial.html

22. How do I change the console background and fonts used in Half-Life?

   http://www.planethalflife.com/wavelength/2dart/articles/wads.html

23. What's a good overall source of Level Editing (mapping) information?

   http://www.planethalflife.com/wavelength/levels/
   http://www.planethalflife.com/wavelength/levels/faqs/faqs.html

24. What's a good overall source of Modeling (weapon models, player models, 
etc.) information?

   http://www.planethalflife.com/wavelength/models/reference/faq.html
   http://www.planethalflife.com/wavelength/models/tutorials/ModelingTutorial.html

25. What are the various animations available for models in Half-Life?

   http://www.planethalflife.com/wavelength/levels/resources/animations.html

26. What does "Can't get DLL API" mean?

   This error occurs when the Half-Life engine can't find the DLL in your
   MOD's dll subdirectory.  The most common cause of this error is in the
   liblist.gam file in your MOD directory.  Make sure the gamedll entry in
   the liblist.gam file is "dlls\mp.dll" and NOT "dll\mp.dll" (without the
   `s').  Also make sure that you HAVE a dlls subdirectory in your MOD
   directory and that there is a mp.dll file in that directory.

27. How do I get Blood to show up in my MOD?

   Blood was disabled in the Standard SDK released by Valve.  To turn Blood
   back on, you will need to modify the player.h file found in the dlls
   subdirectory of the SDK.  Add the following line right after the line
   that says "void Pain( void );".

      int BloodColor() { return BLOOD_COLOR_RED; }

28. Why does the game crash or lock up when I build the client.dll file?

   You need to turn off the Microsoft Visual C++ Inline Function Expansion
   option.  See the previous question in this FAQ about how to build the
   client.dll file.

29. What does "Bad entity in IndexOfEdict()" mean?

   This error occurs in Half-Life when something (model, weapon, sound,
   etc.) is attempted to be used before it is PRECACHED.  Precaching loads
   things into memory so that they are ready to be used.  Failure to
   PRECACHE something will cause this error to occur and will cause
   Half-Life to exit.

   See the ClientPrecache() function in client.cpp (in the dlls directory)
   for examples of how sounds and models are precached.

   See the W_Precache() function in weapons.cpp (in the dlls directory) for
   examples of how weapons and ammo are precached.

30. Why doesn't my newly created weapon show up in the game?

   This is probably because you didn't PRECACHE the weapon.  You will need
   to precache the weapon using the UTIL_PrecacheOtherWeapon() function.
   This should be done in the W_Precache() function in weapons.cpp.

31. How do I make a driveable (controllable) vehicle in Half-Life?

   This question has been asked many, many times and so far, no one has come
   up with a solution.  Maybe you will be the one that writes the tutorial
   on "Creating a driveable vehicle in Half-Life".

32. Where do I find the API reference for the Half-Life SDK?

   There isn't one (yet).  All of the tutorials and articles available on
   the Internet came from people who were willing to sit down with the SDK
   source code and determine how things worked for themselves.  When they
   learned how to change something or create something new, they took the
   time to write a tutorial so that the rest of us could benefit from their
   effort.  Just like I took the time to sit down and compile this list of
   common questions about creating a MOD for Half-Life.  Maybe one day there
   will be a complete list of all of the classes, functions and variables
   found in the Half-Life SDK with detailed descriptions on each of these,
   but until this happens, the best way for you to understand what can be
   done is to examine the source code yourself to try to understand how
   things work.


The information contained within this FAQ is the sole opinion of botman and
should NOT necessarily be taken as absolute fact.  I have tried to be as
accurate as possible with the information herein, but if you are aware of
mistakes or inaccuracies, please e-mail me with corrections using the e-mail
address found on my web site at http://jump.to/botman/

