Runtime loading for GDNative libraries
APACHE-2.0 License
Allows for runtime loading of GDNative libraries for Godot 3.4.x.
Useful for making parts of your game/application optional to users. An example of where this would be useful would be making a lip-sync library optional or using a mock library if it's not available.
This script is really only useful for exported projects that wish to make some features optional. If possible, you should instead rely on CICD to package your game/app appropriately.
GDScript
runtime_loader = RuntimeLoader.new("res://example/plugins/" if OS.is_debug_build() else "")
runtime_loader.scan()
pinger = runtime_loader.create_class("pinger", "Pinger")
if pinger != null:
print(pinger.ping())
config.ini
# Library metadata that's technically optional
# If omitted, defaults will be used, however it's generally better to be explicit
[General]
# These all map back to GDNativeLibrary resource properties
symbol_prefix="godot_"
reloadable=true
load_once=true
singleton=false
# Only use the following option if you are sure you need it
init_func_name="my_init_func"
# A section must exist for each target platform
# Target platform names map back to the names in a GDNativeLibrary resource
[Windows.64]
# The name of the library in the current folder
# In theory, this will also work in a nested folder as long as you provide a relative path
lib="rust.dll"
# All other sections are used to define classes in the library
[Pinger]
# This is the only field needed in order to generate a NativeScript resource
extends="Reference"
A full example is provided as a release. The ponger
library is deliberately misconfigured in order to showcase error handling. It is trivial to fix. If you cannot figure out how to fix ponger
's configuration, this addon is too advanced for you.
addons/gdnative-runtime-library
directory into your addons folderplugins
folder at your project root (next to your executable for exported projects)config.ini
file for each plugin (e.g. plugins/my_gdnative_lib/config.ini
)config.ini
(see the example
project for an example. Note that the dll
s are not checked into this repository, but you can download the exported release for a runnable example)gdnative_runtime_loader.gd
file with an optional path
arg (By default this searches for a plugins
folder at your project root, but this can be customized)scan()
in order to parse the librariesinit
hook, you will need to pass those args now to the library (e.g. runtime_loader.libraries["my_lib"].add_init_arg(1))
to add an init arg 1
to a library called my_lib
)runtime_loader.create_class("my_lib", "foo")
to create a class called Foo
from the my_lib
library)