The Whole Half-Life
Level design resources for GoldSource, Source, and beyond
Featured map: Riverpool by Rimrook
Half-Life Programming - Getting Started History
See all pages See all uploads See all categories

Half-Life Programming - Getting Started Last edited 2 months ago2024-09-01 09:46:44 UTC

  1. Wiki
  2. View Page

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 to avoid it, you need it. On other platforms, use the editor of your choice, as the approach is quite a bit different to Windows.

Git

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, a lot of people have forked the Valve repository and made various updates to it - such as fixing the code, adding some features and some quality of life improvements (and sometimes, those were made before they got "official"-ized by Valve). TWHL member Solokiller has such a fork called halflife-updated which updated the project to support new versions of Visual Studio and GCC/G++ before Valve did it with the HL25 SDK update. 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.
Disclaimer about Half-Life version compatibility
Solokiller's Half-Life: Updated is not compatible with WON and obsolete Steam versions of Half-Life. It might work with Xash but it's not supported.

These guides will assume by extension that you are using the latest version of Half-Life on Steam. If you want to support WON and/or Xash, please consider using another Half-Life SDK that meet that requirement.
Linux users: Valve's default repository expect the SDK to be built with the Steam Runtime (the version 1 code-named "scout" like the Team Fortress 2 class to be exact). This means that sandboxing/containers are involved and this could be "scary" for beginners as this is an entire different setup. The halflife-updated repository on the other hand allow you to build the binaries natively thus making the learning/development experience way easier and faster.

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/twhl-community/halflife-updated.git

Visual Studio

Linux 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 libgl1-mesa-dev. 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 Visual Studio version you'll be using, these instructions will be different. However, this guide assumes you're using the latest version of Visual Studio (2022 at the time this page is updated), 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 Visual Studio 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 (even if you are using a Visual Studio different than 2019) and it should be good to go.

Setting up liblist.gam

Before you can start compiling code and testing your mod you'll need to add a file called liblist.gam to the mod directory. This is a configuration file that tells the engine and Steam some things about your mod.

Here's what it looks like: 
game "Test Mod"
type "singleplayer_only"
startmap "c0a0"
trainmap "t0a0"
gamedll "dlls/hl.dll"
gamedll_linux "dlls/hl.so"
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 file are:

Adding delta.lst

A second configuration file called delta.lst is needed for your mod to work correctly. This file tells the engine how to send data between the client and server. The default file included with Half-Life has a couple mistakes, so make sure to grab the file from the SDK you're using and put it in the mod directory next to the liblist.gam file.

You'll find this file in the network directory in the SDK.

If you are using Half-Life Updated on Windows then this file will be copied automatically when you compile the source code.

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. In Notepad, open the filecopy.bat file in the root folder of the SDK. Find where it sets the mod directory and change it to your mod folder inside your Steam install of Half-Life.
    • For example, if your mod is called mymod, and you have Steam installed in C:\Steam, then you would update the line in filecopy.bat to be:
      • set mod_directory=C:/Steam/steamapps/common/Half-Life/mymod
  2. Now switch to Visual Studio. 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.
    • The platform toolset should be either v142 (Visual Studio 2019) or v143 (Visual Studio 2022).
    • 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.
  3. In Visual Studio, press Ctrl+Shift+B or go to Build -> Build Solution. Wait for it to finish.
  4. 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
  5. 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 you need to setup a Steam Runtime "scout" environment and that's a different beast to setup and use.
  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 libgl1-mesa-dev. Make sure these are GCC 9 or newer versions, you can run gcc -v and g++ -v in a terminal to check these.
  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:
Before: 
void CWorld::Precache()
{
    // .... some code here
After: 
void CWorld::Precache()
{
    ALERT(at_console, "Hello, world! (from server)\n");
    // .... some code here
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:
Before: 
void CHud::VidInit()
{
    // .... some code here
After: 
void CHud::VidInit()
{
    gEngfuncs.Con_Printf("Hello, world! (from client)\n");
    // .... some code here
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!

(Windows) Common "first time" compile errors

This is a list of frequent common "first time" compile errors that beginners can get when building the Half-Life SDK on Windows:

Cannot open include file 'crtdbg.h / ctype.h': No such file or directory (compiling source file <some source file here>)
Two situations where this error can happen: 'HSPRITE': 'int' differs in levels of indirection FROM 'HSPRITE__*'
This error is caused by a Windows header (usually Windows.h) being included which defines HSPRITE which conflicts with Half-Life's version. The common case for this error is using an old Half-Life SDK with modern Visual Studio versions.
To fix this: do not include Windows headers directly, try using the existing Half-Life headers pattern like extdll.h, util.h, cbase.h if you're on the server project or hud.h, cl_util.h if you're on the client one. If you have no other option, you can try to include the Windows headers this way.

'vec3_t': undeclared identifier
You likely copied/pasted code from a project and/or tutorial using an old Half-Life SDK base. Half-Life: Updated removed this redundant type, you can replace it by Vector.

2 Comments

brannanz
brannanz
Commented 3 years 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
jamie
jamie
Commented 2 years 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.