Skip to main content
Version: bleeding-edge ๐Ÿฉธ

C Module

C Module is a Package type that allows extending the functionalities of nanos world Scripting API

C Modules allows you to extend the functionality of the nanos world scripting API on the server side. Currently only C modules are supported.

caution

Be aware that this part of the scripting API is currently work in progress and may change at any time.

caution

This is an advanced procedure so instabilities and even crashes may occur.

danger

C Modules are native code with full access to the server machine, so they can only be loaded if the server is started with the --enable_unsafe_libs flag. Without it, the server refuses to load any c-module Package. Only enable it if you trust all the Packages running on your server.

Also note that C Modules only run on the server side: their binaries are never sent to clients.

Creating your C Module binariesโ€‹

To create your own module, first make sure you have Visual Studio installed with Desktop development with C++ (and CMake) or any other C compiler on Linux.

First Stepsโ€‹

  1. Then, clone our example module in your computer to get start with it.
  2. After cloning, you will need to download it's submodules with git submodule update --init --recursive - this will download the module-sdk as a git submodule into deps/ folder automatically.

Understanding the exampleโ€‹

The important file is under src/example.cpp:

src/example.cpp
loading...

Compiling your C Moduleโ€‹

To compile the example, follow the steps:

  1. Create a folder called build/: mkdir build
  2. Enter the build folder: cd build
  3. Generate the cmake build files with cmake ..
  4. Finally build it with cmake --build . --config Release

This will generate the compiled library at:

  • For Windows: build/Release/example.dll
  • For Linux: build/libexample.so
tip

If you intend to make your module available for both Linux and Windows servers, you must also compile the .so files in a Linux machine and deliver both library files with your Package.

Creating a C Module Packageโ€‹

First of all, create a new Package of type c-module, and add your .dll (windows) and/or .so (linux) files into the Package's root folder. It will look like that:

Packages/
โ””โ”€โ”€ my-module/
โ”œโ”€โ”€ Package.toml
โ”œโ”€โ”€ example.dll
โ””โ”€โ”€ libexample.so

Then add the name of your module library (in our case, example) to the Package.toml modules list, and set lua_version to the Lua version your module was compiled against. The server refuses to load the Package if it doesn't match its own Lua version (currently 5.4):

my-module/Package.toml
# vault configurations
[meta]
# friendly name
title = "My Awesome C Module"
# contributors
author = "Contributor Names"
# version
version = "0.1.0"

# c module configurations
[c_module]
# Lua version the modules were compiled on
lua_version = "5.4"
# list of modules to load (without file extension)
modules = [
"example",
]

Loading and Using your C Moduleโ€‹

Now you can load the package you created as usual, by adding it to the Config.toml's list of Packages requirement or by adding it to another Package's Package.toml as dependency, e.g.:

Server/Config.toml
...
# game configurations
[game]
# default startup map
map = "default-blank-map"
# game-mode package to load (set the main game-mode package to load - you can load only one 'game-mode' package type at once)
game_mode = ""
# packages list (set the packages you want to load)
packages = [
"my-module",
]
...

And in your Package, you can load and use it like:

my-awesome-package/Server/Index.lua
-- Calls the module function 'test'
-- Will print 'Hello World' on console
Console.Log(example.test())