Optimizing Godot Builds for WebGL

Introduction

When developing games with Godot, optimizing build size is crucial—especially for web and mobile platforms where every kilobyte counts. By compiling a custom Godot build, you can remove unnecessary modules, reducing the final executable size and improving performance.

This guide will cover the complete process, from cloning the Godot source code, configuring a custom.py file, and compiling an optimized template with SCons.

Why use Custom Templates?

✅ Smaller builds = Faster downloads
✅ Only includes needed features = Less overhead
✅ Better performance = Optimized for your game

Step 1: Installing SCons

SCons is a Python-based build system used by Godot to compile its engine from source. Unlike traditional Makefiles, SCons offers:

🔹 Cross-platform compatibility
🔹 Dependency tracking
🔹 Automated configuration

Begin by installing Python 3.10 or a later version to guarantee successful package installation via pip.

Open PowerShell and check that pip is correctly installed:

PS C:\Windows\system32> pip --version
pip 24.2 from C:\Install\Python\Python310\lib\site-packages\pip (python 3.10) 👍

To install SCons, continue in PowerShell and run:

PS C:\Windows\system32> pip install scons

Finally, check that SCons is correctly installed:

PS C:\Windows\system32> scons --version
SCons by Steven Knight et al.:
        SCons: v4.9.0.99a8c86de1ce91d23b102520e185c54ebd968924, Sun, 02 Mar 2025 14:04:50 -0700, by bdbaddog on M1Dog2021
        SCons path: ['C:\\Install\\Python\\Python310\\lib\\site-packages\\SCons']
Copyright (c) 2001 - 2025 The SCons Foundation 👍

Step 2: Cloning Godot Repository

To clone a repository from GitHub, the first thing you need to have installed is Git.

RECOMMENDED: GitHub offers a friendly option with GitHub Desktop, which includes Git and simplifies the process.
Alternatively, you can install Git directly from the official site.

You can check if Git is correctly installed by running:

PS C:\Windows\system32> git --version
git version 2.43.0.windows.1 👍

Next, let’s clone the Godot repository from GitHub:

PS [...]> git clone https://github.com/godotengine/godot.git
PS [...]> cd godot

You’re now inside the Godot project folder and ready to compile the engine. After cloning the repository, list the available tags to identify the version used by the Godot Editor you’re using to develop your game. Then, check out that specific tag into a new branch:

PS [...]\godot> git tag -l
...
4.1.3-stable
4.1.4-stable
4.2-stable
4.2.1-stable
4.2.2-stable
4.3-stable
4.4-stable 👈
...
(END)
PS [...]\godot> git checkout tags/4.4-stable -b 4.4-stable-custom

For example, in my case, I’m developing my game with Godot 4.4 stable, so I check out the 4.4-stable tag

IMPORTANT: After this step, Now, make sure your console is in the root folder of the cloned Godot repository.

Step 3: Creating a custom.py for Build Optimization

To remove unnecessary modules and optimize the build size, create a custom.py file in cloned godot root folder.

Example custom.py file:

debug_symbols = "no"
module_mobile_vr_enabled = "no"
module_multiplayer_enabled = "no"
module_openxr_enabled = "no"
module_webxr_enabled = "no"

What does this do?

🔹 Disables debug symbols (reduces file size)
🔹 Removes unused modules (e.g., XR, networking)

Tips for setting up custom.py

TIP 1: You can generate a custom.py file using the following tool:

👉 https://godot-build-options-generator.github.io/

TIP 2: Alternatively, you can list all available SCons parameters using this command:

PS [...]\godot> scons platform=web target=template_release verbose=1 --help
scons: Reading SConscript files ...
...
scons: done reading SConscript files.

platform: Target platform (web|windows)
    default:
    actual: web
    aliases: ['p']

target: Compilation target (editor|template_release|template_debug)
    default: editor
    actual: template_release
...

⚠️ TIP 3: Be careful when disabling modules — some have dependencies and can’t be removed freely. To check a module’s dependencies, look inside the modules folder. Each module has a config.py file where you’ll find a line like:

env.module_add_dependencies("MODULE_NAME", ["DEPENDENCIES"])

This tells you which other modules it depends on.

Step 4: Compiling a Custom Template

With your configuration set, it’s time to build the engine.

Clean previous builds:

PS [...]\godot> scons platform=web target=template_release verbose=1 --clean

Compile the new template:

PS [...]\godot> scons platform=web target=template_release verbose=1

This generates a lighter, optimized template for WebGL inside bin folder. Replace platform=web with linux, windows, or android as needed.

TIP: Install Binaryen to perform additional optimizations once your custom template has been generated.

PS [...]\godot\bin> wasm-opt godot.web.template_release.wasm32.nothreads.wasm -o godot.web.template_release.wasm32.nothreads.opt.wasm -all --post-emscripten -Oz

Step 5: Replacing Default Templates in Godot Editor

After compiling your custom template_release, open your Godot Editor where you are developing your game and replace downloaded default templates in Editor Settings → Export Templates to use the customized build we have created with SCons.

Conclusion

By exporting your Godot game with custom templates, you can remove unnecessary features and reduce the build size, making your game leaner and more efficient. This is especially beneficial for web, mobile, and console games where size and performance are critical.