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
// Module definition
GMOD_MODULE( Init, Shutdown );
int Init( lua_State *L )
g_Lua = Lua();
int Shutdown( lua_State L )
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.
This is just something you need to remember. It speeds up compiling on Windows, because it skips certain Win32 functions that are rarely used.
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();
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 )
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 ' 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
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: