Tooling

The tools that build, format, and validate Godot.

Build: SCons

SCons is the build system. Entry point: SConstruct. Per-directory build descriptors: SCsub. Shared helpers: methods.py, *_builders.py.

Most-used invocations:

scons platform=linuxbsd target=editor dev_build=yes
scons --help                # full option list
scons -j$(nproc)            # parallel
scons compiledb=yes         # emit compile_commands.json
scons scu_build=yes         # single compilation unit (faster)
scons custom_modules=path1,path2   # add external modules

Code-generation steps SCons drives:

• core/object/make_virtuals.py — generates virtual method binding boilerplate.
• gles3_builders.py, glsl_builders.py — turn GLSL/Godot-shader source into C++ string constants.
• editor/editor_builders.py — bakes editor strings, certificates, code-completion data.
• editor/template_builders.py — minimal export template manifest.
• core/core_builders.py — bakes version_hash.gen.h, the global constants, AES key.
• tests/test_builders.py — generates the test case registration glue.

Pre-commit hooks

.pre-commit-config.yaml is the contract. Install once:

pip install pre-commit
pre-commit install

The hooks include:

Hook	Tool	Catches
clang-format	clang-format 21.1.7	C++ formatting (.clang-format in repo root)
clang-format-glsl	clang-format with misc/utility/clang_format_glsl.yml	Godot shader / GLSL formatting
clang-tidy (manual)	clang-tidy 21	C++ lints (.clang-tidy); requires compile_commands.json; runs on core/, main/, scene/ only today
ruff-check, ruff-format	ruff	Python lint + format
mypy	mypy 1.19+	Python type-check
codespell	codespell	Common typos in source
check-jsonschema	jsonschema	Validates core/extension/gdextension_interface.json against its schema
make-rst	doc/tools/make_rst.py	Class reference XML round-trips correctly
doc-status	doc/tools/doc_status.py	Class reference coverage doesn't decrease
validate-builders	tests/python_build/validate_builders.py	Builder Python scripts produce expected output
validate-xml	misc/scripts/validate_xml.py	XML class refs validate against doc/class.xsd
validate-codeowners	misc/scripts/validate_codeowners.py	.github/CODEOWNERS covers every path
validate-includes	misc/scripts/validate_includes.py	Header includes follow the project's ordering
eslint	ESLint 9	JavaScript in platform/web/js/ and module web shims
jsdoc	JSDoc	Web engine JS API docs build cleanly
svgo	svgo	Editor SVG icons are minified consistently
copyright-headers	misc/scripts/copyright_headers.py	Each source file has the MIT copyright header
header-guards	misc/scripts/header_guards.py	Headers use #pragma once
file-format	misc/scripts/file_format.py	UTF-8, LF endings, no trailing whitespace, final newline
dotnet-format	dotnet format (via wrapper)	C# formatting in modules/mono/glue/

clang-tidy is the only manual hook — invoke explicitly:

pre-commit run --hook-stage manual clang-tidy --files <changed files>

clang-format

Configured in .clang-format. Highlights:

• Tabs for indentation, width 4.
• LLVM base style with project-specific tweaks: AccessModifierOffset: -4, AlignAfterOpenBracket: DontAlign, AllowShortFunctionsOnASingleLine: Inline, Cpp11BracedListStyle: false, RemoveSemicolon: true, Standard: c++20.
• AttributeMacros registered: _ALWAYS_INLINE_, _FORCE_INLINE_, _NO_INLINE_.
• IncludeBlocks: Regroup with project-specific category priorities — see Patterns and conventions.

Re-format the entire codebase if you ever change .clang-format:

pre-commit run clang-format --all-files

clang-tidy

.clang-tidy enables a curated set of clang-tidy checks. The workflow:

1. Generate compile_commands.json: scons compiledb=yes.
2. Run: pre-commit run --hook-stage manual clang-tidy --files <files>.
3. Or run directly: clang-tidy -p compile_commands.json --fix path/to/file.cpp.

The hook is currently scoped to core/, main/, and scene/ because the rest of the codebase still has unresolved warnings.

Python tooling

pyproject.toml configures ruff, mypy, and the project's general Python dev tools. Run them via pre-commit, or manually:

ruff check . --fix
ruff format .
mypy SConstruct methods.py *_builders.py

CI workflows

.github/workflows/ contains the GitHub Actions YAML. Roughly:

• static_checks.yml — pre-commit + doc lints. Fast.
• linux_builds.yml, macos_builds.yml, windows_builds.yml — multi-target build matrix.
• android_builds.yml, ios_builds.yml, web_builds.yml — mobile + web.
• runner.yml — shared runner setup (caching, deps installation).

Each build job optionally runs bin/godot --headless --test if tests were compiled.

CODEOWNERS

.github/CODEOWNERS maps directories to maintainer teams or individuals. Reviewers are auto-assigned based on the touched paths.

Other helpers

• doc/tools/make_rst.py — converts doc/classes/*.xml to RST for the docs site.
• doc/tools/doc_status.py — reports class reference coverage.
• tests/create_test.py — scaffolds a new doctest test case.
• misc/scripts/copyright_headers.py — adds/updates the MIT header on a file.
• misc/scripts/file_format.py — normalizes whitespace and BOMs.