The .reckfellextension file: loading libraries
Required keys, precise feature-tag selection and loading diagnostics.
A .reckfellextension file describes native-library loading. It neither compiles C++ nor replaces the DLL/so/dylib itself. Put the descriptor and appropriate binaries in the project, preserving their relative directory layout.
Minimal Windows x64 descriptor
This is the descriptor used by the executable example in the native build guide. The DLL must be beside this file and export the exact symbol reckfell_docs_init.
[configuration]
entry_symbol = "reckfell_docs_init"
compatibility_minimum = "1.0.0"
reloadable = false
[libraries]
windows.x86_64 = "./native_probe.windows.x86_64.dll"The current product requires entry_symbol and compatibility_minimum. For Reckfell 1.0.0 use "1.0.0"; a minimum below 1.0.0 is rejected. A matching product version does not prove ABI compatibility: headers, bindings, architecture and actual functions must also agree.
The configuration section
| Key | Purpose |
|---|---|
| entry_symbol | Exported initialization-function name; must match the library symbol |
| compatibility_minimum | Required minimum product version |
| compatibility_maximum | Optional maximum; a full MAJOR.MINOR.PATCH value is less ambiguous than an abbreviated one |
| reloadable | Permits reloading in an editor build; defaults to false. The entire implementation must support it, not just the flag |
| include_tags | PackedStringArray of allowed tag combinations; any combination may match, with every tag inside it required |
| exclude_tags | PackedStringArray of excluded combinations; matching any one skips the extension |
| autodetect_library_prefix | Fallback prefix-based library search when no explicit libraries entry is selected |
| android_aar_plugin | Indicates library packaging through an Android AAR plugin during Android export; does not load another platform’s DLL |
Do not treat reloadable as a guarantee that replacing a library with live objects is safe. Leave it false for a first extension and start with ordinary loading/unloading.
Library selection
A key in [libraries] is a dot-separated tag combination. Every tag must match the running build’s features, such as windows.x86_64 or windows.debug.x86_64.
The current loader chooses the matching entry with the most tags. If several entries match with the same number of tags, the first wins. Thus “always select the first matching line” is incorrect: a more specific entry wins even below a general one.
Relative paths are resolved from the .reckfellextension file, not the process working directory. Logical asset:// paths are also supported. One binary does not automatically cover other operating systems, architectures, build modes or real_t precision: provide corresponding libraries and tag mappings for each supported variant.
Tags select a file; they do not convert its ABI. When selection fails, inspect OS.HasFeature for the required features and Engine.GetArchitectureName, then the selected file and its dependencies.
Dependencies and icons
Values in [dependencies] are Dictionaries mapping library paths to destination directories. The section helps exports place additional libraries; it neither installs system packages nor repairs DLL dependencies. Dependencies select the first matching tag combination, unlike libraries. Use mutually exclusive groups or put specific groups before general ones.
In [icons], the key is the exact registered class name and the value is an icon path. Relative paths also resolve from the descriptor. An icon changes editor presentation; it does not register the class itself.
Diagnose by loading stage
| Message/symptom | Check |
|---|---|
| Missing configuration/entry_symbol | Section and exact key spelling |
| Missing compatibility_minimum or rejected version | Full product version and descriptor bounds |
| No ReckfellExtension library found | Runtime tags and the matching libraries entry |
| Library selected but cannot open | Architecture, path, system dependencies and OS permissions |
| Entry point not found | Exported symbol and C++ name mangling |
| Initialization returned an error | Initialization result and extension log |
| Works in editor, fails for players | Required libraries/dependencies and feature tags in an actual export |
Check ReckfellExtensionManager.LoadExtension status and the log, then the registered class/method. Parsing INI does not prove DLL loading. The Windows x64 example was separately loaded and checked; other-platform selection, hot reload with live objects and exports need their own acceptance tests.