Godot 通过 GDExtension 配置 C++ 开发环境

Godot 通过 GDExtension 配置 C++ 开发环境

本文介绍在 Godot 引擎中使用 GDExtension 配置 C++ 开发环境的流程。主流手段为 GDExtension，需配合官方维护的绑定库。

环境准备

安装 Visual Studio 和 Godot（建议使用最新 4.5 版本）。

获取绑定库

从 GitHub 下载官方维护的绑定库：godot-cpp。 参考官方文档说明：编译插件。

目录结构

创建主文件夹，包含以下结构：

• demo-cpp/：Godot 项目
• demo-cpp/bin：存放编译后的 C++ 扩展 DLL
• godot-cpp/：下载的 C++ 绑定库
• src/：编写的 C++ 扩展代码

配置 SCons

在根目录创建 SConstruct 文件。确保安装 SCons（可通过 Miniconda 管理 Python 环境）。 参考配置如下：

#!/usr/bin/env python
import os
import sys
env = SConscript("./godot-cpp/SConstruct")
env.Append(CPPPATH=["src/"])
sources = Glob("src/*.cpp")
if env["platform"] == "macos":
    library = env.SharedLibrary(
        "demo-cpp/bin/libgdexample.{}.{}.framework/libgdexample.{}".format(
            env["platform"], env["target"], env["platform"], env["target"]
        ),
        source=sources,
    )
elif env["platform"] == "ios":
    if env["ios_simulator"]:
        library = env.StaticLibrary(
            "demo-cpp/bin/libgdexample.{}.{}.simulator.a".format(env["platform"], env["target"]),
            source=sources,
        )
    else:
        library = env.StaticLibrary(
            "demo-cpp/bin/libgdexample.{}.{}.a".format(env["platform"], env["target"]),
            source=sources,
        )
else:
    library = env.SharedLibrary(
        "demo-cpp/bin/libgdexample{}{}".format(env["suffix"], env["SHLIBSUFFIX"]),
        source=sources,
    )
Default(library)

注意路径配置，特别是项目名。

创建扩展配置文件

在 Godot 项目中手动创建 bin 目录，并添加 gdexample.gdextension 文件用于链接项目和扩展。 示例配置：

[configuration]
entry_symbol = "example_library_init"
compatibility_minimum = "4.5"
reloadable = true
[libraries]
windows.debug.x86_64 = "res://bin/libgdexample.windows.template_debug.dev.x86_64.dll"
windows.release.x86_64 = "res://bin/libgdexample.windows.template_release.x86_64.dll"
linux.debug.x86_64 = "res://bin/libgdexample.linux.template_debug.x86_64.so"
linux.release.x86_64 = "res://bin/libgdexample.linux.template_release.x86_64.so"
macos.debug = "res://bin/libgdexample.macos.template_debug.framework"
macos.release = "res://bin/libgdexample.macos.template_release.framework"
ios.debug = "res://bin/libgdexample.ios.template_debug.xcframework"
ios.release = "res://bin/libgdexample.ios.template_release.xcframework"
android.debug.x86_64 = "res://bin/libgdexample.android.template_debug.x86_64.so"
android.release.x86_64 = "res://bin/libgdexample.android.template_release.x86_64.so"
[dependencies]
ios.debug = { "res://bin/libgodot-cpp.ios.template_debug.xcframework": "" }
ios.release = { "res://bin/libgodot-cpp.ios.template_release.xcframework": "" }

填写编译到 bin 目录下的库文件地址。

IDE 配置 (VS Code)

在 VS Code 配置目录下创建 c_cpp_properties.json、tasks.json、launch.json 三个文件。

1. c_cpp_properties.json：改善 C++ 项目的智能感知。
2. tasks.json：配置通过 IDE 启动 SCons 编译动作。
3. launch.json：配置编辑器的调试运行。

c_cpp_properties.json 示例：

{
  "configurations": [
    {
      "name": "Win32",
      "includePath": ["${workspaceFolder}/**"],
      "defines": ["_DEBUG", "UNICODE", "_UNICODE", "TOOLS_ENABLED", "DEBUG_ENABLED", "TESTS_ENABLED"],
      "windowsSdkVersion": "10.0.26100.0",
      "compilerPath": "cl.exe",
      "cStandard": "c17",
      "cppStandard": "c++17",
      "intelliSenseMode": "windows-msvc-x64"
    }
  ],
  "version": 4
}

tasks.json 示例：

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "build-extension [dev build]",
      "group": "build",
      "type": "shell",
      "command": "cmd",
      "args": ["/c", "conda activate godot_scons && scons compiledb=yes dev_build=yes"],
      "problemMatcher": "$msCompile"
    }
  ]
}

参数说明：

• compiledb=yes：生成 compile_commands.json，辅助智能感知。
• dev_build=yes：编译调试用的 dev 版本 DLL。

launch.json 示例：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Run Project in Editor",
      "type": "cppvsdbg",
      "request": "launch",
      "program": "<godot_exe_path>",
      "args": ["--editor", "--path", "${workspaceFolder}/demo-cpp", "--verbose", "--debug", "--stdout"],
      "stopAtEntry": false,
      "cwd": "${workspaceFolder}"
    },
    {
      "name": "Run Project in Game",
      "type": "cppvsdbg",
      "request": "launch",
      "program": "<godot_exe_path>",
      "args": ["--path", "${workspaceFolder}/demo-cpp", "--verbose", "--debug", "--stdout"],
      "stopAtEntry": false,
      "cwd": "${workspaceFolder}"
    }
  ]
}

preLaunchTask 可配置启动前的前置任务（如先编译）。

配置完成后，在 VS Code 中通过 Shift+Ctrl+P 呼出命令行，选择运行生成任务即可编译。 建议安装 godot-tools 插件以增强体验，并在编辑器设置中启用外部 IDE。该插件可显示场景节点树结构，支持快速打开 GDScript 代码。

总结

Godot 的 C++ 扩展开发体验良好，主要优势包括：

1. 可直接在扩展的 C++ 代码中下断点进行调试。
2. 修改代码后直接编译，无需重启编辑器即可查看变化，接近脚本语言体验。