构建系统

SCons 构建，入口 SConstruct（1238 行）。核心思路：平台靠 detect.py 插件发现、模块靠 config.py 声明、目录靠 SCsub 累积源文件。

SConstruct 要点

平台发现（:77-109）：遍历 glob("platform/*")，要求子目录有 detect.py，收集 can_build()/get_opts()/get_flags()
核心选项（:161-263）：platform、target（enum: editor | template_release | template_debug，默认 editor）、arch、dev_build（DEV_ENABLED）、optimize/debug_symbols/production/threads；渲染驱动开关 vulkan/opengl3/d3d12/metal/use_volk/angle、xaudio2、accesskit、sdl、tests、werror 等
模块发现（:442-470）：methods.detect_modules("modules") + custom_modules，每个模块加 module_<name>_enabled BoolVariable
target 语义（:533-535）：editor_build = target=="editor"；debug_features = target in [editor, template_debug]
组装顺序（:1206-1219）：core → servers → scene → editor(条件) → drivers → platform → modules → tests → main → platform/<platform>/SCsub

SCsub 模式

每个目录一个 SCsub（Python）：Import("env") → 向 env.<area>_sources 累加源文件 → 可嵌套子目录 → 建静态库。例：

core/SCsub：先编 thirdparty 小组件（fastlz/r128/smaz/pcg/polypartition/smolv），按 env["brotli"] 加 brotli
servers/SCsub：SConscript audio/rendering/text/physics_2d/physics_3d/navigation/xr 等，最后 env.add_library("servers", ...)

平台 detect.py

约定函数（以 platform/macos/detect.py 为例）：get_name、can_build()（:20，macOS 检查 darwin 或 osxcross 交叉环境）、get_opts()（:27，平台专属变量如 MACOS_SDK_PATH）、get_doc_classes/get_doc_path、get_flags()（:86）、configure(env)（:95：arch 校验、编译参数、链接库）。

模块注册机制

modules/register_module_types.h：ModuleInitializationLevel = CORE/SERVERS/SCENE/EDITOR 四级（与 GDExtension 对齐），声明 initialize_modules(level)
无手写 register_module_types.cpp：modules/SCsub:24-27 调 modules_builders.register_module_types_builder 生成 register_module_types.gen.cpp（对每个启用模块生成 #ifdef MODULE_<NAME>_ENABLED → initialize_<name>_module(level)）
每模块目录：config.py（can_build/configure/is_enabled/get_doc_classes）+ register_types.cpp/h + SCsub + 可选 doc/
依赖声明：env.module_add_dependencies("gdscript", ["jsonrpc", "websocket"], True)（modules/gdscript/config.py）

methods.py

SCons 共享工具库：源文件管理（add_source_files、SCU 单编译单元加速）、add_library/add_program、模块系统（detect_modules/module_check_dependencies/sort_module_list，排序保证注册顺序稳定）、平台/编译器探测（detect_darwin_sdk_path/get_compiler_version）、版本信息（get_version_info/get_git_info）、VS 工程生成（generate_vs_project）。另有 glsl_builders.py/gles3_builders.py（shader 编译产物）、scu_builders.py、platform_methods.py。

常用命令

scons platform=macos target=editor            # macOS 编辑器
scons platform=linuxbsd target=template_release -j8
scons platform=web target=template_release    # 需 emcc
scons compiledb=yes                            # 生成 compile_commands.json（clangd）

Wiki AI

目录