VLiva Documentation
Plugin API Surface
Core C ABI contract between VLiva host and plugins, based on plugin_api.h.
Direct URL: https://vliva.tamkungz.me/documentation/plugin-api
-
include/vliva/plugins/plugin_api.h -
plugins/example_plugin.cpp
In this page
Section 1
API Versioning
Every plugin should advertise and validate API version compatibility before use.
- Host and plugin must agree on VLIVA_PLUGIN_API_VERSION.
- Changing ABI should increment the API version.
- Mismatch should be rejected by host safely.
c
#define VLIVA_PLUGIN_API_VERSION 1u
Section 2
Host Callbacks (VlivaHostApi)
The host exposes a callback table to plugins. Current API provides a logging callback.
- The pointer is received in on_load(host).
- Always guard callback pointers before calling.
- Future host callbacks can be added in a backward-compatible way.
c
typedef struct VlivaHostApi {
void (*log)(const char* message);
} VlivaHostApi;
Section 3
Plugin Surface (VlivaPluginApi)
Plugin returns a function table that host can call during lifecycle events.
- name() returns plugin display name.
- on_load() runs once when plugin is initialized.
- on_frame() is called every frame with timing values.
- on_unload() runs once before plugin is removed.
c
typedef struct VlivaPluginApi {
uint32_t api_version;
const char* (*name)(void);
void (*on_load)(const VlivaHostApi* host);
void (*on_unload)(void);
void (*on_frame)(double time_seconds, float delta_seconds);
} VlivaPluginApi;
Section 4
Factory Symbol (create_plugin)
Shared library must export a factory function returning VlivaPluginApi.
- Host resolves symbol with C ABI naming.
- Function returns a stable pointer to plugin API table.
- Returned table should stay valid for plugin lifetime.
c
typedef const VlivaPluginApi* (*VlivaCreatePluginFn)(void);