Binary Modules

Binary modules allow you to change or extend the behavior of Pragma without having to change the core source code. Binary modules are written in C++ and loaded during runtime using Lua (with some special exceptions). Some example modules are:

• pr_chromium: Adds an integrated Chromium-based Web Browser to Pragma
• pr_openvr: Adds virtual reality support to Pragma
• pr_bullet: Adds support for the Bullet physics engine to Pragma
• pr_physx: Adds support for the PhysX physics engine to Pragma
• pr_curl: Adds support for the curl library to Pragma
• pr_sqlite: Adds SQLite support to Pragma

Installing Modules

If the binary module is available on GitHub, you can use the following console command to install the module directly:

install_module <GitHubUser>/<RepoName>

For instance, if you want to install the pr_curl module, simply run install_module Silverlan/pr_curl in the console, which will automatically download the module and install it.

Alternatively, if a binary module comes with prebuilt binaries, you can simply extract the archive to your Pragma installation directory, the file structure in the archive should ensure that its placed in the correct location. Simple modules that consist of a single library file can usually be found in the "modules" directory, while more complex modules (like chromium) reside in their own sub-directory within "modules".

The module can then be loaded with a simple Lua-script:

local moduleName = "chromium/pr_chromium"
local result = engine.load_library(moduleName)
if(result ~= true) then
    console.print_warning("Failed to load \"" .. moduleName .. "\" module: " .. result)
    return
end

The module name is the path to the binary file, without the "modules/" prefix and without the file extension. On Linux the module file also has the "lib" prefix, which has to be omitted as well. For instance, if the module filename is "modules/curl/libpr_curl.so", then the module name should be "curl/pr_curl".

Building Modules

If you want to build a module manually, follow the instructions for building Pragma, and add the following argument when running the build script:

--module <name>:<gitUrl>

For instance, if you want to add the pr_chromium module:

--module pr_chromium:https://github.com/Silverlan/pr_chromium

(You can use the --module argument multiple times if you want to add more than one module.)

The build script will clone, build and install the module automatically. If you want to make any changes to the module afterwards, you can run the following command to rebuild and reinstall it without having to re-run the build script every time:

cmake --build --target pr_chromium pragma-install

Custom Modules

Setting up your own custom module is very simple and only takes a few minutes using the Pragma module template repository on GitHub, which also includes workflows for automated builds and releases.

To do so, go to the template repository and create a new repository from it:

You can choose whatever name you want for the repository, but for consistency it is recommended that it should have the same name as the module, which means:

• It should start with the "pr_" prefix
• It should be all lowercase
• It should only contain letters and underscores

Some examples are: "pr_chromium", "pr_bullet", "pr_audio_fmod", etc.

Next click "Create repository from template" to generate the repository.

The generated repository now contains a bunch of template files, which still need to be initialized. For that, you will first have to enable write permissions for workflows in the repository settings:

Next, open the file "template_pragma_module.json" on GitHub and edit the values within:

• "name": A pretty name, which will appear in the generated readme.
• "module_name": The internal name of the module (i.e. the name of the CMake target and the binaries). This name should always start with the prefix pr_ and always be lowercase. It should match the repository name if possible.
• "install_directory": The directory where the module should be installed to, relative to the Pragma installation. This should be somewhere in modules/. If you know that the module will require additional files aside from the main binary, you should change this path to a sub-directory of "modules".

Now commit your changes. This will trigger a workflow which will initialize the repository with your values, which should take about two minutes. Simply refresh the page a few times, once you can see the following icons at the top of the readme, it means the initialization was completed:

The initialization will also trigger the automated build workflows, which may take a few hours to run. Once they have completed, the two icons should turn green, and you should find the compiled binary files available for download for both Windows and Linux in the "Releases" section of the repository.

The build workflows will automatically trigger whenever you push any new commits to the repository and the release binaries will be updated every time. If there are any errors during the build process, the icons will say "failing" again, and you can check the workflow log for more information on what caused the failure.

Stable Releases

If your module has reached a state that can be considered "stable", you can publish a stable release. To do so, wait for the regular build workflows to complete, then go to the "Actions" tab of your repository and select the "Create Stable Release" workflow, enter a version number and click "Run workflow":

This workflow should only take a minute, as it just publishes the latest binaries as a new release.