How a native extension works
Library, C interface, metadata, registration and access boundaries.
ReckfellExtension connects native code through a separate library and a C interface. An extension is built separately; adding a library through the available API does not require rebuilding the engine itself.
Its parts
| Part | Purpose |
|---|---|
| DLL/so/dylib | Your compiled native code for a specific platform |
| .reckfellextension | Entry point, feature-tag library selection, version bounds and packaging data |
| reckfellextension_interface.h | C types and function pointers for engine interaction |
| reckfellextension_interface.json | Machine-readable description of that low-level interface |
| extension_api.json | Class, method, built-in type and size metadata for bindings; not merely a list of C functions |
A language wrapper is an additional layer over this contract. The mechanism itself is not a programming language. C# Entity/Resource code normally uses the managed SDK integration without a native-library descriptor. C# can still call registered native API through the available integration, so saying the systems have “no relation” is misleading.
Loading path
- The manager receives a descriptor and selects a library for active OS/architecture features.
- The loader opens it and resolves the exported entry_symbol.
- The entry function receives the resolver, library pointer and initialization structure. Required C functions are resolved by exact name.
- Initialization registers classes/constants at an appropriate level. The examples use Scene with Entity as the base class.
- Project code uses the registered API. Deinitialization callbacks remove registrations when the extension shuts down.
Classes need correct creation and lifecycle data. The tutorial’s abstract class deliberately cannot be instantiated: it proves registration and constant transfer rather than an arbitrary game component’s implementation.
Boundaries
Using C/C++ does not automatically expose private Source classes or functions. If the required operation is absent from the interface or available API, use another extension point or a separately built engine module/change.
Product version, architecture, built-in numerical precision, header and metadata must agree. Check resolved function availability and the actual required method; a retained SDK name can be a stub. The example and its limits apply to the installed build, not a promise about every future version.
Distinguish object ownership, temporary Variant representations and opaque handles. Each function’s contract determines who creates and destroys data; copying object bytes does not transfer its state and lifetime to another process.
Continue
The C17 example provides a complete small ABI-check project. Library descriptors cover binary selection and loading failures. Interface metadata is for binding authors.