Settings and reference / USER GUIDE
Installing and managing plugins
Plugins add control panels and image filters to HarmoFlow. This page explains how to use files you have received. To create your own, see Creating plugins. For the color correction, tone curves, and gradient maps available out of the box, see Built-in adjustments.
- CheckConfirm type, author, compatibility, and save your scene
- AddSelect the file in the manager and check its load status
- LaunchOpen it from Plugins and try it in a test scene
First, identify the file type
| Type | Where to add or run it | Main purpose |
|---|---|---|
Lua extension (.lua) | Plugins → Add / Browse Plugins... | Register a panel with sliders and buttons to group layer operations together |
DLL plugin (.dll) | The same add/browse screen | Register image filters and other features using native code. Requires a Windows x64 build |
Regular Lua script (.lua) | Window → Scripting (Lua) → Run / Run File... | Run an hf API operation once. This is separate from registering a panel |
A regular Lua script and a Lua plugin extension are different, even though both use the .lua extension. A Lua file added as a plugin must use hf.register_panel to register a panel. Passing a regular script to the add/browse screen will not create the plugin panel you expect.
Before adding a plugin
Save your current scene and check the source of the file and the HarmoFlow versions it supports. DLLs are native code that runs in the same process as the app. Lua extensions have some restrictions, but they do not run in an isolated environment that guarantees safety. Use files only from authors you trust.
From installation to launch
- Open Plugins → Add / Browse Plugins... in the top menu.
- Choose Add Plugin... and select the distributed
.luaor.dllfile. - The file is copied to the app's storage location and loading begins. Lua extensions register after painting and other ongoing operations finish. Check the registration result in the Lua extensions list, even after the add confirmation appears.
- Open the top Plugins menu again and choose the registered item. The add/browse screen is for management; launch plugins from the Plugins menu.
- Check the results in a small test scene. If the extension adds layers, also check that the layer list contains the intended result.
Added files are considered for loading the next time you start the app. If no item appears in the launch menu, see Troubleshooting loading problems.
The current implementation automatically attempts only the first 16 Lua files, sorted by filename, at startup. A running session can hold up to 32 extensions, but keep extensions/ to 16 .lua files or fewer if all must load again on restart.
Where are the files stored?
When added through the app, files are saved in the following folders next to the HarmoFlow executable. They do not belong in the project folder.
Folder containing the HarmoFlow executable/
├─ extensions/
│ └─ my_panel.lua
└─ plugins/
└─ my_filter.dllUse the same locations when placing files manually. At startup, HarmoFlow looks for files directly inside each folder. Extract ZIP archives and do not put files in deeper subfolders. Use lowercase .lua / .dll extensions. Files copied through the add/browse screen have their extensions converted to lowercase.
The add/browse screen has no option to overwrite a file with the same name. If that name already exists, use the update procedure below.
Updating or removing a plugin
- Save your scene and quit HarmoFlow.
- Locate the relevant file in
extensions/for a Lua extension orplugins/for a DLL. - To update it, back up the old file elsewhere and replace it with the new file. If you no longer need it, move it out of the relevant folder.
- Restart HarmoFlow and check the loading status in the list and the menu item.
There are no dedicated commands to reload, unload, or delete plugins while the app is running. Loading the same DLL again, or adding a renamed Lua extension with the same panel ID, does not update it. A backup left in the same folder with a .dll / .lua extension will also be loaded at startup, so keep backups elsewhere.
Troubleshooting loading problems
| Symptom or message | What to check |
|---|---|
| A file with the same name exists / cannot add the file | Existing files are not overwritten. Quit the app, check the old file, and then replace it |
| No menu item after adding Lua | Check the Lua loading result in the list. Make sure it is an extension that registers a panel with hf.register_panel, rather than a regular script |
| Some Lua extensions are missing after restart | Startup attempts only the first 16 files in filename order, including invalid files. Check the number of .lua files directly inside extensions/ |
| Duplicate Lua panel ID | Check whether an older version or a copy of the same extension remains in extensions/ |
Could not load DLL | Check the author's instructions to confirm it is built for Windows x64 and that the required runtime libraries and dependent DLLs are present |
DLL exports no hf_plugin_init | The HarmoFlow entry point was not found. The DLL may be for another app, or its build configuration may be incorrect |
Plugin init failed or wrong API version | Check which versions the plugin supports and send the loading result to the author |
Already loaded | The same DLL cannot be reloaded. To update it, quit the app, replace the file, and restart |
| A manually placed file is not found | Make sure the file is directly inside the correct folder next to the app, its extension is lowercase, and it has been extracted from its ZIP archive |
Check the distributor's requirements before looking for and adding unfamiliar DLLs from other websites. When reporting a problem, include the HarmoFlow and plugin versions, filename, displayed error, and the steps you used to add it. This makes the cause easier to identify.