Sean's Blog

Godot GDExtension

21分钟阅读

Godot GDExtension 是 Godot 4.0 引入的新扩展系统，它允许开发者使用 C++ 编写高性能的原生扩展。以下是其核心原理：

1 架构概述

GDExtension 基于动态库加载机制工作。Godot 引擎在运行时动态加载编译好的共享库文件（.dll、.so、.dylib），通过标准化的 C API 接口与扩展代码通信。

2 核心组件

GDExtension Interface 这是 Godot 引擎提供的 C API 接口层，定义了扩展与引擎交互的所有函数指针。扩展通过这些函数指针调用引擎功能，如创建对象、调用方法、访问属性等。

绑定层（Binding Layer） godot-cpp 库提供了 C++ 绑定，将底层的 C API 包装成更友好的 C++ 接口。它提供了类型安全的包装器，让开发者能够像使用普通 C++ 类一样使用 Godot 的类型系统。

类注册系统 通过 ClassDB 系统，扩展可以向 Godot 注册新的 C++ 类。这些类可以继承自 Godot 的内置类（如 Node、Resource 等），并暴露属性、方法和信号给 GDScript 使用。

3 工作流程

初始化阶段 当 Godot 加载扩展时，会调用扩展的初始化函数。扩展在此阶段获取 GDExtension 接口的函数指针，建立与引擎的连接。

类型注册 扩展向引擎注册自定义类型，包括类的层次结构、方法签名、属性定义等元数据。这使得这些类型可以在 Godot 编辑器中使用，也可以从 GDScript 访问。

运行时交互 运行时，Godot 通过虚函数表机制调用扩展中的方法。扩展也可以通过接口函数调用引擎功能，实现双向通信。

4 内存管理

GDExtension 使用引用计数机制管理对象生命周期。Godot 对象通过 Ref<T> 智能指针管理，确保内存安全。扩展需要正确处理对象的创建、引用和释放。

5 性能优势

由于 GDExtension 编译为原生代码，避免了解释执行的开销，在数学计算、图像处理、物理模拟等性能敏感场景中表现出色。同时，它保持了与 Godot 类型系统的完全兼容性。

这种设计使得 GDExtension 既保持了 GDNative 的高性能特性，又提供了更稳定的 API 和更好的开发体验。

6 FAQ

6.1 GDExtension 是否只能编译成动态库才能工作，为什么？

GDExtension 是否只能编译成动态库才能工作，为什么？

GDExtension 必须编译成动态库才能工作，这是由其架构设计决定的，主要原因如下：

技术层面的必要性

插件式架构需求 Godot 引擎采用插件式架构设计，需要在运行时动态加载和卸载扩展。静态链接会将扩展代码直接编译到引擎中，无法实现这种灵活性。

内存空间隔离 动态库在独立的内存空间中运行，与 Godot 引擎核心保持隔离。这样即使扩展出现问题，也不会直接崩溃整个引擎，提高了系统稳定性。

ABI 兼容性 不同版本的 Godot 可能有不同的内部结构。动态库通过标准化的 C API 接口与引擎通信，这个接口层抽象了内部实现细节，确保了应用二进制接口（ABI）的稳定性。

加载机制限制

运行时发现 Godot 通过扫描项目文件夹中的 .gdextension 配置文件来发现和加载扩展。这个过程需要在运行时动态执行，静态链接无法支持这种机制。

平台无关性 动态库可以为不同平台编译不同版本（Windows .dll、Linux .so、macOS .dylib），而引擎本身保持平台无关。静态链接则需要为每个平台重新编译整个引擎。

开发和分发优势

模块化开发 开发者可以独立开发、测试和分发扩展，而无需修改引擎源码。这极大地降低了开发门槛和复杂度。

版本管理 不同的扩展可以有独立的版本周期，不受引擎发布周期限制。用户可以选择性地更新扩展而不影响其他组件。

接口设计考虑

GDExtension 的 C API 接口专门为动态链接设计，包括：

  • 函数指针表机制
  • 标准化的调用约定
  • 明确的生命周期管理规则

这些设计都是基于动态库加载的假设，无法直接适配静态链接场景。

总结：GDExtension 的动态库要求不是技术限制，而是架构选择。这种设计实现了灵活性、稳定性和可维护性的平衡，是 Godot 插件生态系统的核心基础。

6.2 godot 还有 module 的概念，其工作原理如何，是否是直接嵌入 godot 引擎的

godot 还有 module 的概念，其工作原理如何，是否是直接嵌入 godot 引擎的

是的，Godot Module 是直接嵌入到 Godot 引擎中的，这与 GDExtension 的动态加载方式完全不同。

Module 的工作原理

编译时集成 Module 是在编译 Godot 引擎时就被静态链接到引擎中的。开发者需要将模块源码放在 modules/ 目录下，然后重新编译整个引擎。

SCons 构建系统集成 每个模块都有自己的 SCsub 文件（SCons 构建脚本），在引擎编译过程中，构建系统会自动发现并编译所有模块，将其链接到最终的引擎二进制文件中。

引擎级别初始化 模块在引擎启动时就会被初始化，成为引擎核心功能的一部分。它们可以注册新的类型、节点类型、资源类型等，这些都会直接集成到 ClassDB 中。

与 GDExtension 的关键区别

特性ModuleGDExtension
加载方式编译时静态链接运行时动态加载
分发方式需要自定义引擎构建独立的库文件
性能最高（无调用开销）高（轻微调用开销）
灵活性低（需重编译引擎）高（即插即用）
内存访问直接访问引擎内部通过 API 接口

Module 的典型应用场景

引擎功能扩展 许多 Godot 的核心功能实际上就是以模块形式实现的，如渲染器后端、音频驱动、网络功能等。

深度定制 当需要修改引擎核心行为或添加底层功能时，Module 是更好的选择。例如添加新的渲染特性、自定义物理后端等。

第三方库集成 将大型第三方库（如物理引擎、音频库）集成到引擎中时，通常使用模块方式以获得最佳性能。

开发和维护考虑

开发复杂度 Module 开发需要深入了解 Godot 引擎内部结构，门槛较高。同时需要维护针对不同引擎版本的兼容性。

分发挑战 使用 Module 的项目需要分发自定义构建的引擎，这增加了部署复杂度。用户无法简单地使用官方引擎二进制文件。

版本绑定 Module 与特定的引擎版本紧密绑定，升级引擎时可能需要大量适配工作。

实现细节

Module 通过以下机制与引擎集成：

  • register_module_types() 函数注册模块提供的类型
  • unregister_module_types() 函数清理模块资源
  • 直接访问引擎的内部 API 和数据结构
  • 可以重写或扩展引擎的核心功能

总结：Module 是引擎内部扩展机制，适合需要深度集成和最高性能的场景，但牺牲了灵活性和易用性。而 GDExtension 则提供了更友好的插件开发体验，适合大多数扩展需求。两者各有适用场景，开发者需要根据具体需求选择。

6.3 动态库加载的最小示例

6.3.1 示例代码

// =============================================================================
// 1. 主程序（模拟 Godot 引擎）- main.cpp
// =============================================================================
#include <iostream>
#include <dlfcn.h>  // Linux/macOS 动态库加载
#include <unordered_map>
#include <string>
 
// 模拟引擎的接口函数表
struct EngineAPI {
    void (*print)(const char* msg);
    void (*register_class)(const char* name, void* class_ptr);
    void* (*create_object)(const char* class_name);
};
 
// 全局类注册表
std::unordered_map<std::string, void*> class_registry;
 
// 引擎提供给扩展的函数
void engine_print(const char* msg) {
    std::cout << "[Engine] " << msg << std::endl;
}
 
void engine_register_class(const char* name, void* class_ptr) {
    class_registry[name] = class_ptr;
    std::cout << "[Engine] Registered class: " << name << std::endl;
}
 
void* engine_create_object(const char* class_name) {
    auto it = class_registry.find(class_name);
    if (it != class_registry.end()) {
        // 这里简化处理，实际应该调用类的构造函数
        std::cout << "[Engine] Creating object of type: " << class_name << std::endl;
        return it->second;
    }
    return nullptr;
}
 
// 扩展初始化函数类型定义
typedef bool (*ExtensionInitFunc)(EngineAPI* api);
 
int main() {
    std::cout << "=== 模拟引擎启动 ===" << std::endl;
    
    // 1. 准备引擎 API 接口
    EngineAPI api = {
        .print = engine_print,
        .register_class = engine_register_class,
        .create_object = engine_create_object
    };
    
    // 2. 动态加载扩展库
    void* lib_handle = dlopen("./libextension.so", RTLD_LAZY);
    if (!lib_handle) {
        std::cerr << "无法加载扩展库: " << dlerror() << std::endl;
        return 1;
    }
    
    std::cout << "[Engine] 成功加载动态库" << std::endl;
    
    // 3. 获取扩展的初始化函数
    ExtensionInitFunc init_func = (ExtensionInitFunc)dlsym(lib_handle, "extension_init");
    if (!init_func) {
        std::cerr << "找不到入口函数: " << dlerror() << std::endl;
        dlclose(lib_handle);
        return 1;
    }
    
    std::cout << "[Engine] 找到扩展入口函数" << std::endl;
    
    // 4. 初始化扩展，传递 API 接口
    if (!init_func(&api)) {
        std::cerr << "扩展初始化失败" << std::endl;
        dlclose(lib_handle);
        return 1;
    }
    
    // 5. 使用扩展注册的类
    void* obj = engine_create_object("MyCustomNode");
    if (obj) {
        std::cout << "[Engine] 成功创建扩展对象" << std::endl;
    }
    
    // 6. 清理
    dlclose(lib_handle);
    std::cout << "=== 引擎关闭 ===" << std::endl;
    return 0;
}
 
// =============================================================================
// 2. 扩展库（模拟 GDExtension）- extension.cpp
// =============================================================================
#include <iostream>
 
// 引擎API接口（与主程序中的定义相同）
struct EngineAPI {
    void (*print)(const char* msg);
    void (*register_class)(const char* name, void* class_ptr);
    void* (*create_object)(const char* class_name);
};
 
// 全局保存引擎API，供扩展内部使用
static EngineAPI* g_engine_api = nullptr;
 
// 模拟的自定义类
class MyCustomNode {
public:
    MyCustomNode() {
        if (g_engine_api) {
            g_engine_api->print("MyCustomNode 构造函数被调用");
        }
    }
    
    void do_something() {
        if (g_engine_api) {
            g_engine_api->print("MyCustomNode 正在执行某些操作");
        }
    }
};
 
// 扩展的初始化函数 - 这是动态库的入口点
extern "C" bool extension_init(EngineAPI* api) {
    std::cout << "[Extension] 开始初始化扩展" << std::endl;
    
    // 1. 保存引擎API接口
    g_engine_api = api;
    
    // 2. 使用引擎API
    api->print("扩展初始化中...");
    
    // 3. 向引擎注册自定义类
    static MyCustomNode dummy_instance;  // 简化处理，实际应该是类元数据
    api->register_class("MyCustomNode", &dummy_instance);
    
    api->print("扩展初始化完成");
    return true;
}
 
// 可选：扩展清理函数
extern "C" void extension_cleanup() {
    if (g_engine_api) {
        g_engine_api->print("扩展正在清理资源");
    }
    g_engine_api = nullptr;
}
 
// =============================================================================
// 3. 编译脚本 - build.sh
// =============================================================================
#!/bin/bash
 
echo "编译主程序..."
g++ -o main main.cpp -ldl
 
echo "编译扩展库..."
g++ -shared -fPIC -o libextension.so extension.cpp
 
echo "编译完成！"
echo "运行: ./main"
 
// =============================================================================
// 4. Makefile
// =============================================================================
# Makefile
CC=g++
CFLAGS=-std=c++17 -fPIC
LDFLAGS=-ldl
 
all: main libextension.so
 
main: main.cpp
	$(CC) $(CFLAGS) -o main main.cpp $(LDFLAGS)
 
libextension.so: extension.cpp
	$(CC) $(CFLAGS) -shared -o libextension.so extension.cpp
 
clean:
	rm -f main libextension.so
 
run: all
	./main
 
.PHONY: all clean run

6.3.2 关键工作流程

1. 接口定义

struct EngineAPI {  // 标准化的C接口
    void (*print)(const char* msg);
    void (*register_class)(const char* name, void* class_ptr);
    // ...
};

2. 动态加载过程

// 主程序运行时加载
void* lib_handle = dlopen("./libextension.so", RTLD_LAZY);  // 加载库
ExtensionInitFunc init_func = (ExtensionInitFunc)dlsym(lib_handle, "extension_init");  // 查找符号
init_func(&api);  // 调用入口函数，传递接口

3. 双向通信建立

  • 主程序向扩展传递函数指针表（EngineAPI）
  • 扩展通过这些函数指针调用主程序功能
  • 扩展向主程序注册自己的类和功能

6.3.3 为什么必须是动态库

符号查找需求

dlsym(lib_handle, "extension_init")  // 需要在运行时查找符号

静态链接后，这个函数调用 就不存在了 会失败，因为符号在编译时就已经解析。

运行时加载 主程序在运行时才决定加载哪个扩展，这种灵活性只有动态库能提供。

内存空间隔离 扩展在独立的内存空间中运行，通过标准化接口与主程序通信。

“静态链接后，这个函数调用就不存在了，因为符号在编译时就已经解析” 是什么意思

静态链接后符号的真实情况

符号并不会 ” 消失 ” 静态链接后，符号信息仍然可能存在于最终的可执行文件中，这取决于编译选项：

# 不strip符号的情况
gcc -static main.cpp extension.cpp -o main_static
nm main_static | grep extension_init  # 可能仍能看到符号
 
# strip后符号才真正移除
strip main_static
nm main_static | grep extension_init  # 这时才找不到

真正的问题：运行时动态查找机制

静态链接缺失的是动态查找能力

// 动态库场景 - 运行时查找
void* lib = dlopen("libext.so", RTLD_LAZY);  // ✅ 可以工作
void* func = dlsym(lib, "extension_init");   // ✅ 可以查找符号
 
// 静态链接场景 - 无法动态查找
// dlsym() 无法在当前进程中查找任意符号名
void* func = dlsym(RTLD_DEFAULT, "extension_init");  // ❌ 通常失败

静态链接的限制

  1. 编译时绑定：函数调用在编译时就确定了地址，无需运行时查找
  2. 缺乏动态发现机制：dlsym() 无法在当前进程中查找任意符号名
  3. 无法实现插件架构：无法在运行时决定调用哪些函数

动态链接的优势 4. 运行时绑定：符号在运行时通过名字查找和解析 5. 支持动态发现：可以通过字符串名字查找函数 6. 插件架构基础：支持运行时加载和调用未知代码

核心问题

我之前说 ” 函数调用不存在 ” 是不准确的。准确的说法是：

静态链接缺失的不是符号本身，而是通过字符串名字进行运行时符号查找的能力。这种动态查找能力是插件系统和扩展机制的基础，只有动态库才能提供。

6.3.4 运行示例

# 编译
make
 
# 运行输出
=== 模拟引擎启动 ===
[Engine] 成功加载动态库
[Engine] 找到扩展入口函数
[Extension] 开始初始化扩展
[Engine] 扩展初始化中...
[Engine] Registered class: MyCustomNode
[Engine] 扩展初始化完成
[Engine] Creating object of type: MyCustomNode
[Engine] 成功创建扩展对象
=== 引擎关闭 ===

这个例子清楚展示了为什么 GDExtension 必须基于动态库：需要运行时发现、加载、符号解析和双向通信机制，这些特性只有动态库才能提供。

6.4 动态库加载的本质

这套机制的核心是: 1.动态加载动态库，查找指定函数符合 2. 建立双向通信通道，引擎可以调扩展函数，扩展内也可以调引擎函数

6.5 拓展和引擎的内存是隔离的,如果引擎函数在堆上构建对象并返回给扩展里的调用者,会有问题吗？

由于引擎和扩展运行在不同的内存空间，直接传递堆对象会导致严重问题。

潜在问题：

  1. 内存管理混乱：引擎在其堆上分配的对象，扩展无法正确释放
  2. 堆不匹配：不同的内存分配器，delete/free 会崩溃
  3. ABI 兼容性：C++ 对象布局在不同编译器间可能不同

GDExtension 的解决方案：

  1. 引用计数系统
// 引擎返回的是句柄/引用，而非直接的对象指针
Ref<Resource> resource = ResourceLoader::load("path/to/file");
// 底层通过引用计数管理生命周期
  1. 接口层抽象
  • 不直接传递 C++ 对象，而是通过标准化的 C 接口
  • 使用 GDExtensionObjectPtr 等不透明指针
  • 所有操作都通过 API 函数进行
  1. 统一内存管理
// 扩展通过 API 请求引擎分配内存
void* ptr = godot_api->mem_alloc(size);
// 必须通过对应的 API 释放
godot_api->mem_free(ptr);
  1. RAII 包装
  • GDExtension 提供包装类自动处理生命周期
  • 确保对象在正确的一侧被创建和销毁

所以虽然理论上存在内存隔离问题，但 GDExtension 通过精心设计的接口层和内存管理策略避免了这些陷阱。

目录

Graph View

反向链接