Binary module tutorial


I’m tired of the fact developing GMod Lua modules in C++ is something reserved for people who can make sense out of the cryptic descriptions on the wiki. That’s the primary reason I decided to write this article. In contrary to the current “documentation”, this article will describe every single step, from getting the required files to compiling your module. Unfortunately I haven’t tried developing GLua modules for Linux yet, so it would be great if someone added the information regarding that. If you’ve been doing C++ for a while, you should be able to get a simple module up and running in about 20 minutes, otherwise stay with me and you’ll be using a simple module in about 40 minutes.


[li]** Microsoft Visual C++ Express** (2005 or 2008 preferred.)[/li][li]Source SDK[/li][li]Basic C++ knowledge (Headers, pointers, classes)[/li][/ul]

Acquiring Lua interface headers

The first thing you need to install are the Lua interface headers. Create a new directory in a location on your PC which you can easily find. Then there’s two ways to acquire the headers.
[li]Extract them using Subversion from this repository.[/li][li]Use Save Link As… or a similar feature in your browser to manually save the files from the repository above in the folder you just created.[/ul][/li]After that, your directory should look like this:

Acquiring Source development files

Start the Source SDK and select the Source Engine 2009 engine version. After that, double click the “Create a mod” menu item.

In the wizard which appears select Modify Half-Life 2 Multiplayer. Then fill in a path you can easily find (e.g. C:/SourceSDK/) and for mod name just fill in something like “SourceSDK”.

Shortly after it has copied all the files, it should come up with “Mod wizard complete” after you’ve clicked Next.

Setting up a module project in Visual C++

Start by creating a new Win32 project. I think it’s useful to use the module name as project name, so I named mine gm_tutorial.

Press OK and a wizard will start. Press Next once and in the following screen select the following project options.

After that, press Finish and you’ve got yourself an empty DLL project. Start by adding a new code file to your project by right clicking the bold project name and pressing Add -> New Item. Select “C++ file (.cpp)” and give it a name you like. Most coders use either the module name again (gm_tutorial.cpp) or call the main file main.cpp. You should now be facing an empty code file in the editor.

Now, first change the project configuration from Debug to Release. It’s in the dropdown menu next to the green play button. After that, right click your project name again and click Properties. Select C/C++ and click on the … button on the right side of the Additional Include Directories textbox. You may have to select it to make the button visible. After you’ve clicked it, an additional window will open. You have to add three directories here:
[li]The folder to which you extracted your GMod Lua headers.[/li][li]In the SourceSDK, you’ll find the folders src/public and src/public/tier1. Add them both.[/li][/ul]
You should end up with something like this:

Now there’s one more thing we need to change before your project is ready. Select General on the left and change the setting Character Set to Use Multi-Byte Character Set.

Your first module

I’ll start by giving you code to mindlessly copy and paste into the code file you created above. Before I’m going to explain how to write a module, we’re going to verify you configured your project correctly first. So, first paste the following code:
[cpp]// Skip rarely used Windows API functions

// Headers
#include <GMLuaModule.h>

// Module definition
GMOD_MODULE( Init, Shutdown );

// Globals
ILuaInterface* g_Lua;

// Initialization
int Init( lua_State *L )
g_Lua = Lua();

return 0;


// Shutdown
int Shutdown( lua_State L )
return 0;
If you set up your project correctly, pressing F7 (or Build -> Build Solution in the menu at the top) should return something like this:
[cpp]1>gm_tutorial - 0 error(s), 0 warning(s)
========== Rebuild All: 1 succeeded, 0 failed, 0 skipped ==========[/cpp]
If it returns 1 failed and displays errors, see Troubleshooting before continuing. If it compiled correctly, then congratulations! You’ve just compiled your first module! Unfortunately, it doesn’t do anything at all and what are all these weird functions? I will now tell you what the code you just pasted does.
[cpp]#define WIN32_LEAN_AND_MEAN[/cpp]
This is just something you need to remember. It speeds up compiling on Windows, because it skips certain Win32 functions that are rarely used.
[cpp]#include <GMLuaModule.h>[/cpp]
This is the header you need to include to tell Visual Studio about the Lua module interface.
[cpp]GMOD_MODULE( Init, Shutdown );[/cpp]
This is a macro with which you define the functions that are called when your module is loaded and unloaded, respectively the initialize and shutdown functions. You can see that the functions Init and Shutdown are defined a bit lower. We’ll get to those in a minute.
This defines a global pointer to the Lua interface given to you by Garry’s Mod. It’s a class you will use to communicate with Lua from your module. We’ll get to that in the next chapter.
[cpp]int Init( lua_State *L )
g_Lua = Lua();

return 0;

We just defined that Init is the initialization function, so this will be the first function that’s called when your module is loaded. Lua() is a function defined in one of the Lua module headers and returns the pointer to the Lua interface described above. You return 0 to let Garry’s Mod know your module loaded successfully, just like with regular programs.
[cpp]int Shutdown( lua_State *L )
return 0;
We defined that this function will be called as soon as the module is unloaded. This will happen when the map changes or when the server shuts down.


While developing, there’s a few common errors that happen to come up. Here are a few common ones and their solutions.

error C2664: 'Msg' : cannot convert parameter 1 from 'const char [6]' to 'const tchar *'

You’ve forgotten to set Character Set to Use Multi-Byte Character Set in your project properties under General.

fatal error C1083: Cannot open include file: 'tier1/utlvector.h': No such file or directory

You haven’t entered the correct path to the Source SDK headers or perhaps you accidentally switched to Debug configuration?

fatal error C1083: Cannot open include file: 'GMLuaModule.h': No such file or directory

Same as above, but for the GMod Lua headers.


I hope you liked this introduction to coding GMod Lua modules. It may seem a bit long, but I wanted to make sure everyone understood everything. Now that you’ve got a working project, you can continue learning about the Lua interface [by reading the whole article]( The whole article is way too big to put in a thread!

If you’ve got any problems and the troubleshoot section doesn’t help you out, just leave a message here. Also, I don’t have a lot of experience with this myself, so if you see something that is wrong, don’t hesitate pointing it out. I’ve tested all of the code myself, so you should have no problems running the snippets.

Happy module coding! :dance:

Rated informative, because you deserve it for all that hard work

woo :smiley: gonna give this a try sometime ^^
good work :smiley:
but, i skimmed over it quickly, but i can’t seem to see what the module in this example does :3

The example doesn’t do anything, this part of the tutorial purely explains how to set up your project, because that’s where most people get stuck.

It’s a good tutorial though, everyone has to admit.

A quick test to see if everything works is to just print a debug message using: “gLua->Msg(‘cunna fag’)”

Also you should be using Team Fortress 2 rather then HL2 EP2.


Very informative

Why not EP2?

Very helpful thank you! I’m gunna try and make one today or tomorrow.

Because GMOD is currently moving over to the TF2 engine, so it would make more sense to use TF2.

I asked Darkspider for something like this a few days ago, and he just linked me to this thread today. Thanks a lot for this Overv!

so if you know, make gm_downloadurl.dll simple http file server

And that has what to do with this thread?

Oh my god I love you.

Awesome, I was just telling you yesterday how I hated the fuss with this stuff. This tutorial totally helped me.

Small nitpick:

g_Lua->GetReturn( 0 )->GetFloat()

The ILuaObject returned from ILuaInterface::GetReturn is never unreferenced.

Other than that, good job.

Really nice tutorial. You might want to add some stuff on functions though.

This is not the whole tutorial, it continues on the wiki: **[GLuaModule](**

maybe add a link like you just did instead of a plain link in your first post :slight_smile:
easy to miss clearly :stuck_out_tongue:

This is great stuff! An article on how to access the HL2 engine functions would be awesome and useful if possible. Like a more advanced section.