Half-Life Programming - Getting Started Last edited 4 days ago2022-08-15 14:38:47 UTC

Half-Life Programming

While developing your mod, you might end up wanting to modify the built-in entities or add entirely new ones, add weapons or NPCs, make changes to the HUD, or a number of other things that require using the Half-Life SDK to update your mod's code. This book (once complete) attempts to guide you through most of the common changes you might want to make.
Please note that this is not a tutorial on how to read or write code. It's expected that you already have programming experience when reading these guides.

Want to learn programming? There are many online guides and tutorials available. Knowledge of C++ is quite useful, as that's what the SDK is coded in. However, if you have a good grasp of higher level languages such as JavaScript, C#, or Java, you should be able to adjust to C++ reasonably quickly. Search online to find the right tutorial for you, but here are some resources to get started (these are taken from a Google search, quality not guaranteed):
With that out of the way, let's get started!

What you will need

First of all, you'll need to get your programming environment set up. In Windows, this is Visual Studio. Don't try and avoid it, you need it. On other platforms, use the editor of your choice, as the approach is quite a bit different to Windows.


If you've done any programming, you probably already know how to use Git, or at least are familiar with it. Make sure Git is installed on your computer before you continue. On Windows, download Git from https://git-scm.com/. On Linux, you probably already have Git installed - otherwise, use your distribution's package manager to install it (e.g. sudo apt-get install git on Debian/Ubuntu, adapt the command if you use another Linux distribution).

If you would like to learn more about using Git, visit: https://git-scm.com/book

The Half-Life SDK

You have a few options here. Valve's official SDK is hosted on GitHub - if you want to start from the official base, then this is the code you need. However, the project is configured for Visual Studio 2010 only, and the newer versions are easier to find and use. A lot of people have forked the Valve repository and made various updates to it - such as fixing the code and project files to work properly with newer versions of VS. TWHL member Solokiller has such a fork called halflife-updated which updates the project to support new versions of Visual Studio and GCC/G++, as well as some changes to reduce the number of warnings or potential issues. This is the repository that these guides will be referencing. Each tutorial has a branch in this fork of halflife-updated, which is maintained by Penguinboy for the purposes of this guide.

The summary of your options is basically: From here on, these guides will assume you'll be using the halflife-updated repository - however, all of the changes will work in any version of Visual Studio.

Linux users: Valve's default repository requires some files to be updated in order to work properly, existing code might require an update as well on modern GCC/G++ versions. It's recommended that you use the halflife-updated repository as well.
Mac users: Just follow the Linux instructions and hope it works. OSX likes to break things and Valve doesn't like to fix them, so it's possible Half-Life just doesn't run at all anymore due to OSX dropping support for 32-bit applications.

Once you've chosen which repository to get, use Git to clone it by running this on the command line (substitute the URL for the repository you want to use):
git clone https://github.com/Solokiller/halflife-updated.git

Visual Studio

Linux/Mac users: Obviously this doesn't apply to you. However, you do need to install some things, if you don't already have them. This command will take care of that: sudo apt-get install build-essential gcc-multilib g++-multilib. This is for 64-bit Ubuntu/Debian, you will need to change this command to suit your own distro if required.

Based on your decision on which repository and VS version you'll be using, these instructions will be different. However, this guide assumes you're using the latest version of VS2019. 2017 is extremely similar, whereas 2010 is a little different, but mostly only when you're installing - after that, it's much the same.

The free Community edition of VS can be downloaded here: https://visualstudio.microsoft.com/downloads/

When installing, make sure you select Desktop development with C++ in the workloads section. Make sure the following optional components are selected as well, in the Individual components section: Finish the installation and you're ready to go. Open projects\vs2019\projects.sln and it should be good to go.

Your first compile

Now that your environment is set up, let's compile the project and make sure the changes work in your mod. If you've not set up a mod already, do it now. The key is to make a liblist.gam file. Here's mine:
game "Test Mod"
hlversion "1110"
type "singleplayer_only"
startmap "c0a0"
trainmap "t0a0"
allowspectators "0"
mpentity "info_player_deathmatch"
gamedll "dlls/hl.dll"
gamedll_linux "dlls/hl.so"
cldll "1"
This file needs to put placed in the root of your mod directory, next to the cl_dlls and dlls directories.

Then restart Steam to get it to appear in the game list.

The important things to note about the liblist.gam are:

How to compile

How to compile will depend on which operating system you're on. See the section below that's appropriate for you:

Windows (Visual Studio)

  1. Before your first compile, go into the properties of each project in the solution and make sure the Windows SDK Version and Platform Toolset settings are configured correctly for the tools that you have installed.
    • For XP support, the platform tools should be v141_xp. Otherwise, it should be either v141 (VS2017) or v142 (VS2019).
    • The Windows SDK Version doesn't matter, you just need one installed for it to work. Drop down the box and select one that you have installed - if one of the options is "Latest installed version", select that.
  2. In Visual Studio, press Ctrl+Shift+B or go to Build -> Build Solution. Wait for it to finish.
  3. Next, you'll need to copy the DLL files into your mod. The hl.dll file goes into the mod's dlls folder, and client.dll goes into the cl_dlls folder. You'll find them here:
    • halflife-updated\projects\vs2019\Debug\hldll\hl.dll
    • halflife-updated\projects\vs2019\Debug\hl_cdll\client.dll
  4. Run your mod and hope it works!
Note: As you work on your mod, you'll find manually copying the DLL files really annoying. It's a good idea to set up a post-build step in Visual Studio to copy the files after each build. The setup needed for this is explained in the Half-Life Programming - Debugging tutorial, so go there when you're ready for more details.

Linux (make)

A note about Linux and this book
This book has been written for a 64-bit (amd64) installation of Ubuntu and you'll need to adapt any commands if you are still using the 32-bit architecture (i386) and/or another Linux distribution.
These instructions are for the halflife-updated repository - if you're using Valve's official repository, it's going to be tough to get Linux going, because some files require an update as well as some code changes for modern GCC/G++ versions to work.
  1. If you haven't already, install the dependencies you'll need to build. This is what you'll need to run in a terminal to get everything needed: sudo apt-get install build-essential gcc-multilib g++-multilib. Make sure these are GCC 9 or newer versions.
  2. In a terminal, navigate to the linux folder of the repository, and run make. Wait for it to finish.
  3. The compiled files are in the linux/release folder. Copy hl.so into you mod's dlls folder, and client.so into the cl_dlls folder.
  4. Run your mod and hope it works!

Making your first changes

Let's make a small change to make sure everything is working properly. Open world.cpp inside the hldll project and find the method void CWorld :: Precache( void ). Let's add a line to the beginning of this:
void CWorld :: Precache( void )
    g_pLastSpawn = NULL;
    // .... more code
void CWorld :: Precache( void ) { ALERT(at_console, "Hello, world! (from server)\n"); g_pLastSpawn = NULL; // .... more code
This change will simply print Hello, world! to the console when any map is loaded. This is the server project, so let's make a similar change to the client project to make sure that's working as well. Open hud.cpp inside the hl_cdll project and find the method void CHud :: VidInit( void ). Here's the change to make here:
void CHud :: VidInit( void )
    m_scrinfo.iSize = sizeof(m_scrinfo);
    // .... more code
void CHud :: VidInit( void ) { gEngfuncs.Con_Printf("Hello, world! (from client)\n"); m_scrinfo.iSize = sizeof(m_scrinfo); // .... more code
Now let's make sure they worked properly. Start your build by following the instructions above, and copy the compiled binaries into to the correct place in your mod.

Before you launch the mod, make sure that you go into the launch properties in Steam (right click on mod > Properties... > Set launch options...) and set them to -console -dev. This ensures that you see developer messages in the console. Now launch your mod and start a new game.

Assuming everything is working, you should see the messages appear somewhere in the console (there are a lot of messages, so don't miss them!).
If you see the message, you're all set up!If you see the message, you're all set up!


Commented 1 year ago2021-05-27 09:53:45 UTC Comment #103578
This didn't work for me because I didn't have the Build Solution option for some reason.

after eight months, i now have the build solution option. it doesn't work. my brain is fried

i was an idiot and didn't change the build path to where i actually want the dlls to go to
Commented 1 month ago2022-06-25 18:48:55 UTC Comment #104582
Honestly i completed this tutorial knowing almost nothing about C++. I learned C++ with this tutorial. Sounds impossible, but i made it lol

You must log in to post a comment. You can login or register a new account.