This is a template repository you can use to write plugins for Unifier.
Note
Once you have read through everything below and know what you're doing, you're free to replace this README file with whatever you want.
We've added a Pylint workflow as of September 20! With this workflow, you'll be able to detect issues in your code as you make commits your Plugin repository, so you can fix them before you release your Plugin.
Please note that our workflow only detects errors (such as SyntaxErrors, ImportErrors, etc, not warnings, refactors, etc). If you need to detect more issues in your Plugin, you are free to modify the workflow to your liking.
To add this workflow to an existing repository, please copy it to .github/workflows/pylint.yml.
plugin.json contains the metadata of your plugin, such as the plugin ID, name, etc. Unifier will read this file on boot, so it knows which files to load to load your plugin.
Below are the list of values you may have in your plugin.json file. Unless otherwise stated, all keys are compatible with Unifier v1.2.0 (release 36) and newer.
Plugin ID. Unifier uses this as the identifier for your plugin, and no plugin installed to your bot may have the same ID. Users will need to specify the ID as the plugin when running install, uninstall, and upgrade for plugins.
Plugin name. Unlike plugin IDs, this can be whatever you desire.
Plugin description. Describe what your plugin does here.
Plugin version. We recommend you follow semantic versioning for this.
Plugin release number. Unifier will use this to tell if the plugin is up to date or not.
The minimum Unifier release required to use your plugin.
Warning
We haven't documented this yet, but we will in the near future.
Services your plugin will provide. Instance owners will need to review and allow services in order for the plugin to be installed. Services include:
content_protection: Plugin provides content filtering. Grants access to message content and moderation actions.content_processing: Plugin provides content processing (e.g. message stylizing). Grants access to message content.emojis(v2.0.1+/rel51+): Plugin provides an emoji pack. An emoji.json file must be present, as well as emojis (can be images or GIFs) in an emojis folder.
Warning
If services is not empty, you will need to have a file called [plugin_id]_[service].py that
provides the service, and it should be added in utils.
Dependencies the plugin needs other than the ones in Unifier's requirements.txt file.
If your plugin needs special code being ran before being unloaded, set this to true.
Warning
If this is true, your plugin will not be able to be unloaded without a [plugin_id]_check.py
file. You will need to specify this in the utils key.
Plugin modules. All files in here will be loaded as an extension when loading the plugin.
Plugin utility scripts. If shutdown is true, you must have [plugin_id]_check.py in here.
Need an example to know what you need to have in your repository? You might want to check out unifier-revolt.
To install a plugin, run the install <repo_url> command. This will install a plugin from the
Git repository you specified.
As Unifier is AGPLv3 licensed, your plugin must be licensed AGPLv3 as well.