Making a Plugin

package.json

package.json tells Freedeck how to handle your package (duh), but also retains full compatibility with NPM. Here’s the most basic package Freedeck will allow:

{
  "name": "myfirstplugin",
  "version": "1.0.0",
  "description": "My First Plugin!",
  "main": "plugin.js",
  "author": "Freedeck",
  "freedeck": {
    "title": "My First Plugin!",
    "package": "plugin"
  },
}

Some keys are retained from the NPM package system, and this is on purpose. However, the “name” key is actually the plugin’s unique identifier. You can modify this to have any data that your plugin will use.

plugin.js

This file can be named whatever you want, only it must be specified in the main part of the package. Here’s a bare minimum implementation that is required for a Plugin to load.

const {Plugin} = require("@freedeck/api");

class MyFirstPlugin extends Plugin {
    setup() {
        return true;
    }
}

module.exports = {
	exec: () => new MyFirstPlugin(),
 	class: MyFirstPlugin
}

Notice how we export a module that has an exec function and a class variable containing the actual class, and NOT the plugin already instantiated. Freedeck verifies the structure of your plugin with reflection and this method before it’s executed. Freedeck also forces some basic checks like the ID being lowercase. It won’t load if you do it any other way. However, this plugin does nothing! Let’s add some functionality where a user can actually add a Tile and press it to send a notification.

const {Plugin, events} = require("@freedeck/api");

class MyFirstPlugin extends Plugin {
    setup() {
        this.on(events.button, this.btn);

		this.register({
			display: "Notify Me",
			type: "mfp.notify"
		});
        return true;
    }
    btn({interaction}) {
        this.pushNotification("You pressed me!");
	}
}

module.exports = {
	exec: () => new MyFirstPlugin(),
 	class: MyFirstPlugin
}

Events? This? Register?

This is the PluginV2 API which is an extension of the legacy Plugin structure left over from before v6.0.0-rc1 . The Plugin works on a registry like structure, you give the server your data, request intents, subscribe to events, and it forwards events made for you back to you. Currently, there is no deny procedure for requesting intents, but the server does block parts of your plugin that extend their reach without requesting it (like the IO intent for access to the server, and SOCKET intent for the individual connection.)

Type Registry

To actually display types, you must go through the Type Registry.

const typeData = {
	display: "Click me", // The display name of the button type
	type: "click.me", // The type identifier
	templateData: {data:1}, // The template data added with the Tile
	renderType: "button", // "button", "slider", "text", or "none"
}

Type vs Interaction

They are used interchangably. A type is an interaction, therefore an interaction is a type. A more concrete definition of a type is: having some data you specify, that Freedeck can display as a configurable tile, that the user can interact with and fire events back and forth. There are multiple render types, with more coming soon.

Display

The display field of an interaction will be shown in the Tile Editor.

Type

The type field of an interaction is simply a unique identifier.

Template Data

Tiles store information, and can store your custom information too. Template data is not used by Freedeck unless you have a slider type, which some fields are required.

Render Types

Render types describe how to actually render your tile.

button

The button is the simplest, the default, and the original concept Freedeck bases itself on. Press it, your event handler will receive an event back, and you can handle the rest.

slider

The slider is the most complex tile type, sending multiple “press” events as the value changes slid by the user. This type requires templateData.

{
	"min": 0, // The minimum the slider is allowed
	"max": 100, // The maximum
	"value": 50, // The first value Freedeck will attempt before the user changes it
	"format": "%", // The "unit" of your slider
	"direction": "vertical" // "vertical" or "horizontal". Vertical is usually used for volume sliders.
}

Events

Events are simply events that you can subscribe to and receive. There are a few currently, connection, button, ready, stopping, stopped.

Connection

The connection event is fired with these parameters:

{socket, io}

Where socket is the current user’s socket.io socket, and io is the socket.io server.

Button

The button event is fired with these parameters:

{interaction, socket, io}

Where interaction is the type data you put when registering it, socket is the current user’s socket.io socket, and io is the socket.io server.

Ready

The ready event is fired with no parameters. It is used to indicate Freedeck’s HTTP server is started.

Stopping

The stopping event is fired with no parameters. It is used to indicate the plugin is going to be terminated, as Freedeck’s main process is shutting down. Use this event to clean up.

Stopped

The stopped event is fired with no parameters. It is used to indicate the plugin IS terminated past this point. This event is not usually receivable due to its nature. Unless it’s a ghost.

Getting Started

Customization

Development Resources

API References

package.json

plugin.js

Events? This? Register?

Type Registry

Type vs Interaction

Display

Type

Template Data

Render Types

button

slider

Events

Connection

Button

Ready

Stopping

Stopped

​package.json

​plugin.js

​Events? This? Register?

​Type Registry

​Type vs Interaction

​Display

​Type

​Template Data

​Render Types

​button

​slider

​Events

​Connection

​Button

​Ready

​Stopping

​Stopped

package.json

plugin.js

Events? This? Register?

Type Registry

Type vs Interaction

Display

Type

Template Data

Render Types

button

slider

Events

Connection

Button

Ready

Stopping

Stopped