botman's bots

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, now called TF 1.5) 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 Half-Life FULL SDK 2.0 file.  The FULL SDK contains all of the source code used to create the DLL in the original game.  The FULL SDK contains all of the Artificial Intelligence (AI) code used for monsters, human military, and scientists found in the original game.  The FULL SDK also contains all of the models used in the original game (plus some additional models that were not used).

You can obtain the FULL SDK from Valve's SDK web page...

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

You can also download the latest SDK from fileplanet...

http://www.fileplanet.com/   (click on the Games: Action, then Half-Life and search for SDK)

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.  Valve uses Microsoft Visual C++ version 6.0 and that is the only officially supported compiler.

When building the HL.DLL file using Microsoft Visual C++ version 5.0, you will need to download and install the Visual Studio 97 service pack 3. You must download the FULL Service Pack and install it.  You can obtain it from here (it's about 91 megabytes)...

http://msdn.microsoft.com/vstudio/sp/vs97/download.asp

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

To build a multiplayer MOD you will only need the Standard SDK 2.0.  The Standard SDK does NOT contain the monster/grunt/scientist AI code found in the Full SDK, so you will not be able to have monsters or grunts or scientists in your MOD unless you code the AI routines yourself.

You can obtain the Standard SDK from Valve's SDK web page...

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

You can also download the latest SDK from fileplanet...

http://www.fileplanet.com/   (click on the Games: Action, then Half-Life and search for SDK)

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.

When building the MP.DLL file using Microsoft Visual C++ version 5.0, you will need to download and install the Visual Studio 97 service pack 3. You must download the FULL Service Pack and install it.  You can obtain it from here (it's about 91 megabytes)...

http://msdn.microsoft.com/vstudio/sp/vs97/download.asp

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.html

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.1.0.6.  You can also download the update file from the following web site...

http://www.fileplanet.com/   (click on the Games: Action, then Half-Life)

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

Download the Standard SDK file and install 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 installed 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 installed 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.  Select "Optimizations" in the "Category:" dialog item.  Then select "Disable" in the "Inline function expansion" dialog item.  Click on "OK" to save these settings.  This will turn off Inline Function Expansion, which causes problems with the DLL if left enabled.

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.thewavelength.net/
http://planethalflife.com/fixxxer/
http://planethalflife.com/hlprogramming/
http://hlpp.telefragged.com/
http://planethalflife.com/hlsdk2
http://www.balfourroad.demon.co.uk/ (botman's mirror)

13. What are some Internet sites with forums (bulletin boards) on Half-Life coding?

http://www.thewavelength.net/forums/
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 Games: Action, then Half-Life)
http://www.thewavelength.net/oldsite/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.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.thewavelength.net/oldsite/2dart/tutorials/sprites.html
http://www.thewavelength.net/oldsite/2dart/articles/advsprites.html
http://www.thewavelength.net/oldsite/2dart/tutorials/spritetutorial.html

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

http://www.thewavelength.net/oldsite/2dart/tutorials/texturetutorial.html

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

http://www.thewavelength.net/oldsite/2dart/tutorials/menututorial.html

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

http://www.thewavelength.net/oldsite/2dart/articles/wads.html

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

http://www.thewavelength.net/oldsite/levels/
http://www.thewavelength.net/oldsite/levels/faqs/faqs.html

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

http://www.thewavelength.net/oldsite/models/reference/faq.html
http://www.thewavelength.net/oldsite/models/tutorials/modelingtutorial.html

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

http://www.thewavelength.net/oldsite/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. I'm getting compiler errors from a tutorial when building the client.dll using SDK 2.0.  What am I doing wrong?

If you are getting error messages like this...

C:\Half-Life\SourceCode\dlls\enginecallback.h(22) : error C2146: syntax error : missing ';' before identifier 'g_engfuncs'
C:\Half-Life\SourceCode\dlls\enginecallback.h(22) : fatal error C1004: unexpected end of file found

...then the client.dll tutorial is probably not written for the SDK 2.0 source code.  Valve changed some of the names of header files in SDK 2.0 and renamed the cl_dll util.h file to cl_util.h.

In the .cpp file you are trying to compile you should see...

#include "util.h"

...change this to...

#include "cl_util.h"

...and it should compile without those errors.

32. How do I get the Standard SDK 2.1 to build using Microsoft Visual C++?

Use the "File->Open Workspace..." menu command to open the "mp.dsp" project file.  This will create a "mp.dsw" workspace file that you can use from now on to open the project.  Once the project is loaded use "Build->Set Active Configuration..." and select the "Win32 Release" version and click on "OK".  Use "Project->Settings...", click on the "C/C++" tab and move the cursor to the end of the "Preprocessor definitions:" line.  Remove the "PERSISTENCE_SAMPLE" string from this line (and the trailing comma after the "VALVE_DLL" entry.) and click on "OK".  Now use "Build->Set Active Configuration..." to select the "Win32 Debug" version and click on "OK".  Use "Project->Settings...", click on the "C/C++" tab and move the cursor to the end of the "Preprocessor definitions:" line.  Remove the "PERSISTENCE_SAMPLE" string from this line (and the trailing comma after the "VALVE_DLL" entry.) and click on "OK".  In the "FileView" tab (on the left of the Microsoft Visual window) open up the "mp files" section and then open the "Source Files" folder.  Scroll down to the "interface.cpp" file.  Click once on it to select it then press the Delete key to remove this file from the project.  Scroll down some more in the "Source Files" folder and click once on the "persistencehelpers.cpp" file to select it.  Press the Delete key to remove this file from the project.  Click on "File->Save Workspace" to save these changes.  Click on "Build->Rebuild All" to build the mp.dll file.

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