Prerequisites

Goals

This tutorial will guide you through the development process.
The examples and the documentation for the server API and client API are also interesting chapters for learning how to develop a plugin.

Assumptions

A plugin is an A.V.A.TA.R overlay running in a Node.js environment. Therefore, developing a plugin assumes that you are completely familiar with Node, npm, javascript and the basics of front-end web development. If you need to do some preliminary reading on the subject before getting started, we recommend the following resources:

Good pratices

It is preferable to have a development orientation before creating a plugin, which will be either:

For personal use.
Added to the A.V.A.T.A.R library for public use.

If it's a personal decision, you'll be the only one using it, so you can ignore this paragraph.
On the other hand, if you choose to share your plugins with the community, you'll need to respect certain conventions:

Localize the plugin: A.V.A.T.A.R is multi-language, so localize at least the current language to allow translation of an existing language pack if necessary.
Add documentation: This part is always overlooked, but it's essential for using the plugin. Depending on the complexity of the documentation, you can choose between :
- Add an information page in Markdown format, which will be displayed in the plugin information page in Plugin Studio.
- Add an HTML document that can be displayed in a web browser.
Note that in both cases, it is preferable to write it in English.
Think multiroom: A.V.A.T.A.R is a client-server application, so make sure that the plugin is always functional even if the client is not installed on the same plateform as the server.
- For example, a classic mistake is to use the server's ffplay application when the music is to be played on a client.
Think multiplatform: A.V.A.T.A.R runs on Windows, Linux and MacOS platforms. There are some differences between systems, so always check that the specific conditions for each platform are respected. If you don't know whether the plugin works on a particular platform, please, advise users in the documentation.
The top!: Bear in mind that there may be clients with operating modes that require special scenarios, for example, some A.V.A.T.A.R clients will use a Wifi speaker controlled by a plug-in, while others will use the PC speaker or that certain clients are mobile clients (e.g. Android), etc.... As a result, some developments may not work in these situations. If you take these scenarios into consideration, then you're on top the top of the contributors!

Required tools

Code editor

You will need a text editor to write your code.
We recommend using Visual Studio Code, although you can choose whichever one you prefer.

GitHub

GitHub is a collaborative development platform built on Git. While neither is strictly necessary to create a plugin, it is indispensable to use the Plugin librairy and managing your source code versions. We also use GitHub project releases (in A.V.A.T.A.R format only) to display them in the Plugin librairy.

So if you don't have a GitHub account, Create a GitHub account now.

Warning

A.V.A.T.A.R is a reserved profile name. Never use this name to name your profile.

You can then use the GitHub Desktop application to manage your projects if you prefer to use a visual interface instead of the command line.

Note

If you're not a contributor, other users won't see your projects and won't be able to download them from the A.V.A.T.A.R plugin library. Your A.V.A.T.A.R GitHub projects will remain personal to you and will be displayed in your library only.

Please note that to become a contributor for public use, you must submit a request. You will then be added as a contributor and users will be able to use your plugins.

nodejs and npm

Although the Electron framework integrates node.js in its executable, it is theoretically not necessary to install nodejs and npm, for A.V.A.T.A.R and to develop a plugin, this installation is mandatory.

Don't worry, this step is made during the installation of prerequisites the server and each client.

npm packages

Developing a plugin means using npm packages in your application.
Some of these packages are accessible by default in node.js, others from packages already installed in A.V.A.T.A.R, but you can also install specific packages to your plugin.

First, check that the package is not a module included in node.js.
- If one exists, then you can import it into the script of the plugin:
```
import * as path from 'node:path';
```

Then open the file A.V.A.T.A.R/resources/app/package.json in a text editor.

Search for the module you are interested in.
If one exists, you can import it into the script of the plugin:
```
import _ from 'underscore';
```

If it doesn't exist:

Open a terminal

Move to the plugin folder

A.V.A.T.A.R (client or server)
    ├── resouces
        ├── app
            ├── core
                ├── plugins
                    ├── Your plugin

Install the package in the plugin folder:
```
> npm install package_name
```

Check package installation:

A.V.A.T.A.R
    ├── resouces
        ├── app
            ├── core
                ├── plugins
                    ├── Your plugin
                        ├── node_modules
                            ├── package_name
                        ├── package.json

Note

If you have created the plugin via Plugin Studio, a package.json file is automatically added to its folder. The package is added to it after the installation.

Danger

Never install a new package in A.V.A.T.A.R client or server packages!

Development terminal and debugging

During development, we prefer to start/stop the server (or client) more quickly from a terminal.
We also prefer to use console.log() to display useful information and error messages.

Open a terminal.

Move to the application's app folder:

A.V.A.T.A.R
    ├── resouces
        ├── app

Start the application with npm:
```
> npm start .
```
You now have an npm console for starting/stopping and viewing messages.

Create a plugin