VLiva Documentation

Example Plugin Walkthrough

Line-by-line practical reference from example_plugin.cpp.

Group: Practical Example

Sections: 4

Source files: 1

Direct URL: https://vliva.tamkungz.me/documentation/example-plugin

plugins/example_plugin.cpp

In this page

Plugin Name
Load / Unload Hooks
Frame Callback
Exported create_plugin

Section 1

Plugin Name

Provide a lightweight static name function that host can display.

Returned string should remain valid throughout process lifetime.
Name can be used in logs, UI list, and diagnostics.

cpp

const char* pluginName()
{
    return "Example Plugin";
}

Section 2

Load / Unload Hooks

Store host pointer on load and emit diagnostics during load/unload.

onLoad caches host API for future calls.
Both callbacks check pointer safety before logging.
Useful pattern for startup and shutdown instrumentation.

cpp

void onLoad(const VlivaHostApi* host)
{
    g_host = host;
    if (g_host && g_host->log)
    {
        g_host->log("Example Plugin loaded");
    }
}

void onUnload()
{
    if (g_host && g_host->log)
    {
        g_host->log("Example Plugin unloaded");
    }
}

Section 3

Frame Callback

Starter plugin keeps frame callback empty for safe baseline behavior.

Use onFrame for per-frame state updates.
Keep work short to avoid host frame drops.
Use timing arguments for deterministic animation logic.

cpp

void onFrame(double /*timeSeconds*/, float /*deltaSeconds*/)
{
    // Keep this no-op as a safe starter plugin.
}

Section 4

Exported create_plugin

Export C ABI symbol returning a static VlivaPluginApi table.

extern "C" prevents C++ name mangling.
Static table keeps function pointers stable.
Host can call this once and retain the pointer.

cpp

extern "C" const VlivaPluginApi* create_plugin(void)
{
    static VlivaPluginApi api = {
        VLIVA_PLUGIN_API_VERSION,
        &pluginName,
        &onLoad,
        &onUnload,
        &onFrame
    };
    return &api;
}