Creating Binary Modules
Binary modules allow you to extend Lua's functionality using C++.
Binary Modules only need CMake and a C++ compiler for building.
You can install both through either the Visual Studio Installer ("Desktop development with C++" in Visual Studio 2019) on Windows, Xcode/homebrew on macOS, or by using your favorite package manager on Linux. For CMake, downloads are also available on the CMake website.
If you want to use an IDE, you should be able to choose any as long as it has support for CMake projects (Visual Studio, CLion, etc.).
If you don't want to use an IDE you can also build the module manually, but that approach will not be detailed in this guide.
The headers you need are available here. They will provide your project with information about how to interface with the game and set a few common settings for compiling the module.
First, create an empty folder. This will contain all the files related to your module and will be referred to as "main folder" from now on.
Now, download a copy of the headers into a subfolder of the main folder.
While you can name it freely, for this guide I will use
gmod-headers as the name of the subfolder.
You will have to replace that name accordingly if you chose something different.
To check whether you extracted the files in the correct location, make sure that the paths
gmod-headers/examples are present in the main folder.
Next, we will set up a CMake project definition.
To do that, create a file called
CMakeLists.txt in the main folder and paste the following content in there:
Now that we have our project defined, we just need something that we can compile into a module.
For demonstration purposes the "Hello World" example works just fine, so copy
gmod-headers/examples/HelloWorld/HelloWorld.cpp and paste it into the main folder as
This file you can now change and experiment with.
For building, simply open the main folder in your chosen IDE (any half-decent one should detect the
CMakeLists.txt file and set up a CMake project) and press "Build" in there.
Developers without IDE can now follow any existing "how to build a CMake project" guide.
The binary module will end up whereever the CMake output was placed, with the correct name already applied.
Userdata and metatables are handled differently in Garry's Mod. This helps the engine determine userdata type much faster.
First create your metatable (ideally in GMOD_MODULE_OPEN), then create a reference to it and store it globally in a variable.
To push your userdata to the stack:
To get your userdata from the stack:
The module files should be placed in the garrysmod/lua/bin/ folder.
The names differ between platform and Lua realm.
||Server||example||Windows x64 (
||Client||example||Windows x64 (
||Server||example||OSX (actually a
||Client||example||OSX (actually a
||Server||example||Linux x32 (actually a
||Client||example||Linux x32 (actually a
||Server||example||Linux x64 (actually a
||Client||example||Linux x64 (actually a