Skip to main content

Your First Plugin

This walks through the smallest plugin that does something observable: it logs a line when FrameLift installs it. It is the same shape as the bundled HelloPlugin example.

1. The source file​

Create MyPlugin.cpp:

#include <framelift/core.h>

class MyPlugin : public PluginBase
{
protected:
    // Required: used as the INI section, settings page title, and log label.
    const char* PluginName() const override { return "MyPlugin"; }

    // One-time setup. Called after all platform services are registered.
    void OnInstall(IPluginContext& ctx) override
    {
        Log::Info("[MyPlugin] hello from the FrameLift SDK!");
    }
};

// Export the plugin's C entry points. .name and .version are required; this
// plugin draws no UI, so it opts out of rendering explicitly with
// .render = false.
FRAMELIFT_PLUGIN_EXPORT(MyPlugin, {
    .name = "MyPlugin",
    .version = {1, 0, 0},
    .render = false,
})

Three things are happening:

  • PluginBase is the recommended base class. It seals the ABI entry points (Install, BindHotkeys) and gives you named hooks like OnInstall to override. See Plugin Lifecycle.
  • Log::Info formats the message in your plugin with std::format, then hands the finished string to the host across a POD sink. No logging library is linked into your DLL.
  • FRAMELIFT_PLUGIN_EXPORT emits the extern "C" functions the host calls to create, destroy, and version-check your plugin, and reports its name + version via framelift_plugin_info(). A plugin that draws UI sets .renderOrder instead of .render = false. See Export Macros.

2. The build file​

Create CMakeLists.txt next to it:

cmake_minimum_required(VERSION 3.28)
project(MyPlugin LANGUAGES CXX)

find_package(FrameLiftSdk REQUIRED PATHS "/path/to/framelift-sdk/cmake" NO_DEFAULT_PATH)

add_framelift_plugin(MyPlugin MyPlugin.cpp ${FRAMELIFT_SDK_SOURCES})
  • find_package(FrameLiftSdk) locates the SDK. It is gated on the ABI major version (SameMajorVersion), so an incompatible-major SDK fails here at configure time rather than at load time; minor compatibility is checked by the runtime loader.
  • add_framelift_plugin declares a plugin DLL target with the right output name and settings. ${FRAMELIFT_SDK_SOURCES} are the SDK helper .cpp files (such as the Log forwarder) that compile directly into your plugin.

3. Build​

cmake -B build
cmake --build build
# → build/Plugins/MyPlugin.dll

4. Load it​

Copy MyPlugin.dll into Plugins/ next to FrameLift.exe, then enable it in the config:

[plugins]
enabled=MyPlugin

Launch FrameLift and check the log — you should see:

[MyPlugin] hello from the FrameLift SDK!

Next​

A plugin that only logs is not very useful. From here:

  • Plugin Lifecycle — every hook PluginBase gives you and when it runs.
  • Settings — persist configuration and add a settings page.
  • Rendering UI — draw your own panel each frame.