Binary modules allow you to extend Lua's functionality using C++.

This page will teach you how to set up your IDE for compiling binary modules using CMake.

For help on interacting with the C Lua API once set up, refer to C Lua: Functions.

Dependencies

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.

Project setup

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/include and 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 module.cpp. 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.

Naming & Location

The module files should be placed in the garrysmod/lua/bin/ folder.

The names differ between platform and Lua realm.