Friction Core Plugins v1.0

Community Core (C++) Plugins for Friction.

Plugins

Hello World v1.0.0

• ID: graphics.friction.plugin.helloworld
• Description: Hello World Example Plugin
• Group: Test
• Author: Friction

Import Text File v1.0.0

• ID: graphics.friction.plugin.importtxt
• Description: Import Text File
• Group: Import
• Author: Ole-André Rodlie
• Supports Import: txt

Linux Power Manager v1.0.0

• ID: graphics.friction.plugin.freedesktop.power
• Description: Will inhibit screen off during playback and inhibit suspend during rendering on Linux.
• Group: System
• Author: Ole-André Rodlie

Linux Render Progress (LauncherAPI) v1.0.0

• ID: graphics.friction.plugin.launcherapi
• Description: Show render progress in the dock or launcher icon on Linux.
• Group: System
• Author: Ole-André Rodlie

Linux System Notifications v1.0.0

• ID: graphics.friction.plugin.freedesktop.notify
• Description: Show system notifications on Linux.
• Group: System
• Author: Ole-André Rodlie

Interface

The FrictionCorePluginInterface defines the C++ contract between your plugin and Friction. Because all methods have default, empty implementations, every method is optional. You only need to override the methods that are relevant to your plugin's functionality.

class FrictionCorePluginInterface
{
public:
    virtual ~FrictionCorePluginInterface() = default;

    virtual void init() {};

    virtual QList<QAction*> createMenuActions(QObject* parent)
    {
        Q_UNUSED(parent);
        return {};
    }

    virtual QList<QAction*> createToolbarActions(QObject* parent)
    {
        Q_UNUSED(parent);
        return {};
    }

    virtual void triggerAction(Document& doc,
                               Canvas* const scene,
                               const QAction *act)
    {
        Q_UNUSED(doc);
        Q_UNUSED(scene);
        Q_UNUSED(act);
    }

    virtual qsptr<BoundingBox> importFile(Canvas* const scene,
                                          const QString &path)
    {
        Q_UNUSED(scene);
        Q_UNUSED(path);
        return nullptr;
    }

    virtual void renderStateChanged(PreviewState state)
    {
        Q_UNUSED(state);
    }

    virtual void renderProgress(int frame,
                                int total)
    {
        Q_UNUSED(frame);
        Q_UNUSED(total);
    }

    virtual void showNotification(const QString& title,
                                  const QString& message)
    {
        Q_UNUSED(title);
        Q_UNUSED(message);
    }
};

virtual ~FrictionCorePluginInterface() = default;

The virtual destructor ensures that any resources, memory, or threads allocated by your plugin are safely cleaned up when Friction is closed or the plugin is unloaded.

virtual void init();

Called exactly once by Friction immediately after the plugin is successfully loaded and registered. Use this method to initialize internal variables, allocate resources, or set up data structures before any user interaction occurs.

virtual QList<QAction*> createMenuActions(QObject* parent);

Requests the plugin to provide a list of actions to be inserted into the plugin menu.

• parent: The menu object. Pass this to the QAction constructor to ensure proper memory management.
• Returns: A list of QAction*. Friction will automatically sort these actions into the sub-menu defined by the group property in your plugin.json file.

virtual QList<QAction*> createToolbarActions(QObject* parent);

Requests the plugin to provide a list of actions to be inserted into the main toolbar.

• parent: The toolbar object. Pass this to the QAction constructor.
• Returns: A list of QAction* representing the buttons you want to add to the toolbar.

virtual void triggerAction(Document& doc, Canvas* const scene, const QAction *act);

The main callback executed whenever the user triggers one of the QActions generated by createMenuActions or createToolbarActions.

• doc: A reference to the Document. Used to access global properties (e.g., document dimensions, framerate, fonts).
• scene: A pointer to the active Canvas. Use this to manipulate the node hierarchy, insert new objects, or alter the selection. (Always verify it is not nullptr before using).
• act: A pointer to the specific QAction that was triggered. You can check act to route logic if your plugin generates multiple different buttons.

virtual qsptr<BoundingBox> importFile(Canvas* const scene, const QString &path);

Triggered when the user attempts to open or import a file matching one of the extensions defined in your plugin's import_extensions JSON array.

• scene: A pointer to the active Canvas, allowing you to reference the current environment during import.
• path: The absolute file path to the file being imported.
• Returns: A smart pointer (qsptr<BoundingBox>) containing the parsed and constructed element hierarchy. Friction will automatically insert this into the active scene and register it with the undo/redo stack. Return nullptr if the import fails.

virtual void renderStateChanged(PreviewState state);

Triggered whenever timeline playback or rendering state changes. This is useful for plugins that need to sync with the timeline, pause background processing during playback, or disable specific UI actions while the application is rendering.

The returned value is of the enum type PreviewState. You can check it against the following values:

• PreviewState::stopped
• PreviewState::rendering
• PreviewState::playing
• PreviewState::paused

virtual void renderProgress(int frame, int total);

Triggered continuously during a rendering or export operation to report the current progress. This is highly useful for plugins that want to display custom progress bars, log rendering statistics, or track when an export is nearing completion.

• frame: The current frame number that has just been rendered or is currently being processed.
• total: The total number of frames in the current rendering task.

Performance Note: Because this method is called very frequently (typically once per frame), you should avoid executing heavy computations or complex UI updates within this callback.

virtual void showNotification(const QString& title, const QString& message);

Triggered by Friction to display a notification. This is typically used to alert the user about the status of background tasks, such as when a long-running rendering or export job finishes, or if a critical background error occurs.

• title: A short summary or heading for the notification.
• message: The detailed body text describing the event.

You can also trigger a notification from a plugin:

emit Document::sInstance->showNotification("foo", "bar");.

Metadata

{
    "id": "graphics.friction.plugin.importtxt",
    "name": "Import Text File",
    "version": "1.0.0",
    "author": "Ole-André Rodlie",
    "url": "https://friction.graphics",
    "description": "Import Text File",
    "import_extensions": ["txt"],
    "group": "Import",
    "api": "graphics.friction.CorePluginInterface/1.0"
}

• id (String, Required): A globally unique identifier for your plugin. Using reverse domain name notation is highly recommended to prevent conflicts in the plugin registry.

• name (String, Required): The human-readable display name of the plugin. This is used in the UI, error messages, and log outputs.

• version (String): The current version of your plugin (semantic versioning like 1.0.0).

• author (String): The name of the developer, team, or organization that created the plugin.

• url (String): A link to the plugin's repository, documentation, or author's homepage.

• description (String): A short summary detailing what the plugin does.

• import_extensions (Array of Strings, Optional): A list of file extensions (without the leading dot) that this plugin is capable of importing. When a user attempts to open a file with a matching extension, Friction bypasses native importers and delegates the process to this plugin's importFile() method.

• group (String, Required): The name of the UI sub-menu where the plugin's generated actions should be grouped. If the sub-menu does not exist, the host will create it automatically.

• api (String, Required): The specific interface version this plugin is built against. This must exactly match the Friction interface. Friction checks this string to verify API compatibility before loading the C++ binary into memory.

Build

In your Friction source repo:

git clone https://github.com/friction2d/friction-core-plugins src/plugins

Now reconfigure your project (Friction will check for src/plugins) and plugins should show up in your IDE (or whatever you use).

As default, plugins will be built in build_dir/src/app/plugins on Linux or build_dir/src/app/friction.app/Contents/MacOS/plugins on macOS.

Plugins search paths (in order):

• Friction app folder/plugins
• Friction app folder/../CMAKE_INSTALL_LIBDIR/friction/plugins
• User config folder/CorePlugins or custom path from settings

Contribute

Fork and make a pull request. Since this is a community repository it's less restrictive than Friction.

License

SPDX-License-Identifier: GPL-3.0-only

All plugins must use this license.