Plugin Developer Manual

To create plugins for Brickadia using Brikkit, you must first know JavaScript. If you do not know it already, I suggest starting with Eloquent Javascript, which is, in my opinion, a good book to learn JavaScript from, and free to read online.

Creating your first plugin

Now we will create your first plugin! Create a directory in the plugins folder, you can call it hello world, for instance. In that directory, create a file named index.js and put the following code in it:

// when a chat event is received
global.Brikkit.on('chat', evt => {
	// if the player said "!hello"
	if(evt.getContent() === '!hello') {
		// broadcast the message "Hello World!"
		global.Brikkit.say('Hello World!'); 
	}
});

Publishing your plugin

The first step in publishing your plugin is checking that it works as you intended. Only after that you can move onto publishing it. To convert your plugin into a package you can send to your friends for them to install, simply zip the contents of your plugin directory (not the directory itself), so that the files in the plugin folder are at the root of the .zip file. After that is done, you can transfer the file to your friends and they can use your plugin by putting the .zip file inside the plugins directory!

To get a plugin published officially on the Brikkit repository, however, it has to be an useful plugin that adds value to a server, and not just a random experiment. It must be released under the MIT license, a free software license that is ideal for small programs, which is the case of plugins. To do this, add a file named LICENSE to your plugin, and put the following text in it, making sure to replace <YEAR> and <COPYRIGHT HOLDER> with the current year and your name:

Copyright <YEAR> <COPYRIGHT HOLDER>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Make sure to understand the terms of the license and what it means for the software you are publishing. If you do not agree with these terms, you are free to not publish plugins on the official repository.

After this step is done, create a git repository inside the directory of the plugin you wish to publish: git init, add all essential files: git add index.js LICENSE.md (and any other files that are required for the plugin to run), and commit your files: git commit -m "First commit". Then, using GitHub, create a repository for your plugin, and push your local git repository there. To conclude this part, create a .zip file of the essential files of your plugin, and create a release, making sure to attach the .zip file that you just created as a binary.

The hardest parts have been done. Finally, create an issue in this repository, with the template below. Your plugin will then be considered for inclusion into the official repository.

Tags: simple, chat
Description: this plugin says "Hello World!" whenever someone says "!hello"
Release: <LINK TO YOUR RELEASE>

Thank you very much for contributing to Brikkit!

Saving and loading data

There are four main directories in a Brikkit installation: brickadia, plugins, conf and saved. Brickadia itself is stored in the first one, whereas plugins are stored in the second. The conf directory is used to store configuration files (you can see an example of this in the autosaver plugin. On the other hand, saved is used to store data between runs of the game, such as how much money each player has. You are free to use any format you deem appropriate in both cases, such as JSON or sqlite3. If you require higher performance, you can also save data to a proper database, but that will require users to install it in order to use your plugin. Finally, if you wish to be on the official repository, your filenames cannot contain, due to a Windows limitation, the following characters: \/:*?"<>|.

Using third party libraries

If you wish to use third party libraries in your plugins, if you are on Windows, it is extremely highly recommended that you use the Windows Subsystem for Linux to execute the following steps.

Install nodejs and npm: # apt install nodejs npm. Move into your plugin directory, and start a npm project there: $ npm init -y. Edit the created package.json file so that the license is MIT.

I will give an example of using the is-odd library. Install the library inside your plugin directory: $ npm install is-odd --save Use it in index.js:

const  isOdd  =  require('is-odd');
console.log(isOdd('3')); // will print true when you start the server

To test the third party library, simply run the server: $ ./brikkit. It should output true at the very beginning assuming this is the only plugin you have.

To package this plugin, zip everything in the folder (including node_modules) and send it to your friends! Alternatively, to publish it, push the package.json and package-lock.json files to the git repository, and create a release with the .zip file as described at the beginning of this paragraph.