Working on Gargantuan

Are you interested in working on Gargantuan? This guide walks through how to compile and work on your own homegrown Gargantuans.

Supported Platforms

Gargantuan works across most major operating systems, which include the latest versions of Windows, MacOS and Linux.

However, older OS versions may lack support for the libraries necessary for Gargantuan to run, and we do not guarantee support nor flawless installation for any of them.

Prerequisites

Windows

WinGet CLI

For dependendency management on Windows, this guide will use the WinGet CLI.

WinGet is usually already pre-installed on most Windows installations and editions. To verify, type the following command into the terminal:

winget --version

WinGet must be available in order to proceed further into the guide.

Caution

If the command doesn’t output anything, then check out the WinGet CLI docs for more information on how to install the WinGet CLI.

Vulkan

For Gargantuan to output graphics, you’ll first need a Vulkan-capable GPU and a working driver for it.

The installation steps for this vary with each system configuration, so this section assumes Vulkan is already properly configured.

Once that is done, install the Vulkan SDK:

winget install -e --id KhronosGroup.VulkanSDK

And with it, verify if Vulkan is properly set up and can detect your GPU correctly:

vulkaninfosdk --summary

Dependencies

Install the Visual Studio 2022 Build Tools:

winget install -e --id Microsoft.VisualStudio.2022.BuildTools --override "--wait --passive --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"

Note

The long --override portion may seem unnecessary, but it is important. The default VS2022 Build Tools package does not guarantee installation of all required C++ dependencies.

This portion explicitly installs the MSVC x64 compiler and linker, Windows SDK, CMake, Ninja, and recommended C++ components needed to build Gargantuan.

Then, install Git:

winget install -e --id Git.Git

And finally, install Rokit:

winget install -e --id Rojo.Rokit

Afterwards, restart your shell in order for the new dependencies to be picked up by PATH.

MacOS

• MacOS 26 and XCode 26
• Vulkan SDK IF you want to test Vulkan via MoltenVK
  • Vulkan SDK comes included with glslc

Homebrew can be used to trivially install CMake, Ninja, and CCache:

brew install cmake ninja ccache

Linux

Vulkan

For Gargantuan to output graphics, you’ll first need a Vulkan-capable GPU and a working driver for it.

The installation steps for this vary significantly with each distribution and system configuration, so this section assumes Vulkan is already properly configured.

Verify that Vulkan can detect your GPU correctly:

vulkaninfo --summary

Dependencies

Install dependencies for your Linux distribution with the following command(s):

Arch Linux

sudo pacman -Syu --needed base-devel cmake ninja ccache shaderc git curl unzip freetype2 libx11 libxext libxcursor libxi libxfixes libxrandr libxss libxtst

Ubuntu

sudo apt install build-essential cmake ninja-build ccache glslc git curl unzip libfreetype-dev libx11-dev libxext-dev libxcursor-dev libxi-dev libxfixes-dev libxrandr-dev libxss-dev libxtst-dev

Debian

sudo apt install build-essential cmake ninja-build ccache glslc git curl unzip libfreetype-dev libx11-dev libxext-dev libxcursor-dev libxi-dev libxfixes-dev libxrandr-dev libxss-dev libxtst-dev

Fedora

sudo dnf install gcc gcc-c++ cmake ninja-build ccache glslc git curl unzip freetype-devel libX11-devel libXext-devel libXcursor-devel libXi-devel libXfixes-devel libXrandr-devel libXScrnSaver-devel libXtst-devel zlib-ng-compat-static libpng-static

openSUSE Tumbleweed

sudo zypper install --no-recommends gcc gcc-c++ cmake ninja ccache shaderc git curl unzip freetype2-devel libX11-devel libXext-devel libXcursor-devel libXi-devel libXfixes-devel libXrandr-devel libXss-devel libXtst-devel

Rokit

Once you have installed dependencies, install Rokit via the automated installer script with curl:

curl -sSf https://raw.githubusercontent.com/rojo-rbx/rokit/main/scripts/install.sh | bash

Afterwards, restart your shell in order for Rokit to be picked up by PATH.

Get the Source Code

Clone the Gargantuan repository and all of its submodules using the following command:

git clone --recursive https://github.com/teamfireworks/gargantuan.git

Caution

If you are an outside contributor, please clone from your own fork of Gargantuan. Team Fireworks can work on the main repository.

Build Gargantuan

Move to the newly cloned Gargantuan directory, and install the tools in rokit.toml:

rokit install

Then, check that the build dependencies are available:

seal scripts/doctor.luau

Gargantuan uses Seal scripts for its development scripts. Configure CMake and generate the Ninja build files with:

seal scripts/configure.luau

Then, compile Gargantuan:

seal scripts/build.luau

After compilation finishes, the Gargantuan executable will be located in build/gargantuan!

Build Options

Gargantuan includes optional Tracy profiling support, but it is disabled by default.

To build the Tracy tools, configure with the --tracy flag, then build their targets:

seal scripts/configure.luau --tracy
cmake --build build --target tracy-profiler tracy-capture tracy-csvexport

Once the tools are built and the engine is running, connect with:

./build/tracy-profiler

tracy-capture -o run.tracy -s 10 records without a window open, and tracy-csvexport run.tracy prints per-zone totals, which is how two runs get compared.

Tracy is disabled by default. Re-run seal scripts/configure.luau without --tracy to disable its tools.

Run Gargantuan

Once built, run the binary directly:

./build/gargantuan --help

Pass either a Luau script or a Gargantuan project:

./build/gargantuan --script path/to/script.luau
./build/gargantuan --project path/to/project

When you make changes in Gargantuan, rebuild, then run the binary again:

seal scripts/build.luau
./build/gargantuan --project path/to/project

Tests are written using the Lest framework. To run the test suite, use:

lest

You’re now fully ready to work on Gargantuan! Make sure to follow our guidelines & best practices for submitting contributions, and have at it :D