Your first plugin

#Your first plugin So you want to write a plugin? That's great news! But before you get started, you should know a bit more about how the plugins are structured and the 3 distinct states a plugin can have and the initialization chain. Furthermore, you should be familiar with the CommonJS/RequireJS module system and have an understanding of NodeJS.

Plugin States

Each Plugin can be in 3 different states at any time. The states are:

Unloaded

The plugin has not been loaded by the internal Plugin Manager. It is available to be loaded at any given time.

Stopped

The plugin has been loaded and is in memory. It has either been just loaded or has been stopped before.

Running

The plugin is running and is doing whatever it is that it's supposed to do.

Initialization and destruction chain

The Plugin has 4 different stages that it may or may not go through while being installed. It is not necessary that you encounter all of these steps.

load

Loading is phase 1 and will always be the first thing your plugin will go through. The Plugin Manager will always load your plugin from your disk to make sure to always grab the most recent version (makes developing very easy). Until next time the plugin is being loaded, the plugin file doesn't get read anymore. This stage is also where the Plugin Manager hands the API Object and a Storage Object to the Plugin. Dependency injection also happens in the load stage.

This stage is meant to do necessary one-time initialization since from that point on the Plugin stays in memory.

Your plugin is now in the Stopped state.

start

Your plugin starts and should do its intended purpose from here on.

Usually, you hook events on the API's EventEmitter here, for example.

Your plugin is now in the Running state.

stop

Your plugin gets stopped by the Plugin Manager and should not do whatever it is designed to while running any longer.

This means that you remove Event Listeners here that you added earlier, for example.

Your plugin is now in the Stopped state.

unload

The plugin gets fully unloaded and removed from memory.

Whatever resources your plugin is still occupying, clean them up here and release and locks you might have placed.

Your plugin is now in the Unloaded state.

meta_inf block

Each plugin must export a meta_inf block, which is giving information about the plugin. The meta_inf block has 5 different, but optional entries:

• name The human readable name of your extension
• version A SemVer compliant version string (Major.Minor.Patch)
• description A short description of your plugin
• author The name of the plugin author
• dependencies An special object for additional dependencies. More on that below

Dependencies

A special feature of the Plugin system is the so called "Dependency Injection". Declaring a dependency in the same format that you are used from a node module's package.json in the dependencies object of the meta_inf takes that entry, directly injects it into the bot's package.json and runs npm install immediately afterwards to retrieve the needed dependencies. This allows any plugin to install whatever node modules it requires to function without much input from the user.

Example dependencies:

dependencies: {
    "request": "^2.69.0",
    "lodash": "^4.3.0"
}

Writing your first plugin

Now that you know the basics of the plugin, lets start with writing a plugin. As already mentioned above, the plugin follows CommonJS/RequireJS Syntax for modules and thus has to export the functions and meta_inf block for the Plugin Manager.

If you want, you can use the following plugin skeleton:

var api; var storage;
module.exports = {
	meta_inf: {
		name: "Your extension name",
		version: "0.0.0",
		description: "Your plugin description here",
		dependencies: {
			// Any dependencies your plugin needs
		}
	},
	load: function (_api, _storage) {
		// This function is optional but highly recommended because
		// it's the only way to get the API and your plugin's storage object
		api = _api;
		storage = _storage;
		// Do any other one-time initialization you might need here
	},
	start: function() {
		// This function is not optional
		// Do Even hooking here and make your plugin begin functioning
	},
	stop: function() {
		// This function is optional
		// Remove Event listeners here and make your plugin stop functioning
	},
	unload: function() {
		// This function is optional
		// Release any locks and free resources that are in use
	}
}

This should be a good starting point for you and the skeleton has everything you need to write your own plugin. It's recommended that you take a look at already existing plugins as well, that should help you out even more.

Finalizing your plugin

Now that you wrote your plugin, just name it <name>.pbot.js and drop the file in your /plugins folder. Load it with plugin enable <name> and test it.

####Thinking your plugin is useful to other people? Open a Pull Request with it and I'll might just add it to the bot!

See also

API - The API Object for all plugins

Storage - The storage for all plugins

Events - What Events does the API fire