Plugin APIs

You have seen some plugins and think they are cool. Now, you want to make a plugin. This is the guide to making one.

What can plugins do?

Plugins effect how the game works. Plugins, can basically do anything. We especially though, made it easy to add game modes or commands through plugins. The OpenAgar plugin system is based off a secure version of FlexiPlugins, another module created by AJS, which, allows us to be very flexible with our plugins.

Table of Contents

Contents
1. Getting started
2. Adding commands
3. Adding gamemodes
4. Events
5. Config files
6. Compiling
7. Publishing
8. Resources

Getting Started

In order to create your first plugin, you must download OpenAgar and "register" it. Registration is free and will be available at the forums. To develop plugins faster, in source/settings/pluginConfig.ini, set dev to 1. This allows any errors to be reported and most importantly, allow uncompiled plugins.

// allowed: A comma separated list of plugins to allow if they dont pass the security test
// dev: If 1, uncompiled (folder) plugins are allowed and errors will be thrown

allowed="plugin"
dev = 0

Next, you must download the template plugin folder. You can download the template here. Then, place that folder into source/plugins in OpenAgar. Open index.js inside the template plugin folder.

module.exports = {
// [General]
name: "", // Name of plugin REQUIRED
author: "", // author REQUIRED
description: '', // Desciprtion
minVersion: '', // minimum version requirements (optional)
version:  '', // version REQUIRED
addToHelp: false, // add to help
 commands: false, // commands
 configFile: false, //config file
// [Functions]
init: function (data,configs) {
  // init, Used to do stuff such as overriding things
}
}

Fill in all the fields that is marked as "REQUIRED". They are crucial for your plugin.

module.exports = {
// [General]
name: "Test plugin", // Name of plugin REQUIRED
author: "AJS Development", // author REQUIRED
description: 'This is a test plugin!', // Desciprtion
minVersion: '', // minimum version requirements (optional)
version:  '1.0.0', // version REQUIRED
addToHelp: false, // add to help
 commands: false, // commands
 configFile: false, //config file
// [Functions]
init: function (data,configs) {
  // init, Used to do stuff such as overriding things
}
}

Then, head over to the next section!

Adding Commands

Adding commands is probably the most used plugin feature. So we have made it very easy to create your own commands.

Essential commands by Andrews54757

In order to create your own commands, change the value of commands from false, to being an object with each command.

Lets add commands!

module.exports = {
// [General]
name: "Test plugin", // Name of plugin REQUIRED
author: "AJS Development", // author REQUIRED
description: 'This is a test plugin!', // Desciprtion
minVersion: '', // minimum version requirements (optional)
version:  '1.0.0', // version REQUIRED
addToHelp: false, // add to help
 commands: {
helloworld: require('./helloworld.js'),
test: require('./test.js')
}, // commands
 configFile: false, //config file
// [Functions]
init: function (data,configs) {
  // init, Used to do stuff such as overriding things
}
}

The code above adds two commands: helloworld and test. But where is the code that makes the command work? Commands are stored in a separate file in the plugin. And they are accessible within the plugin by doing require('./file.js'). In our case, the files are helloworld.js and test.js. Helloworld's file (helloworld.js), would look something like this:

module.exports = function(str,main,log) {
log("Hello world")
}

The str variable, is the string the person typed into the console, the main variable, is the the game object. And the log is the log function.

Never ever use console.log. Always use the log function provided

You can get the arguments the person typed into the console using three ways.

1. The space-separated way

 str = str.split(" ")

The first argument starts at index 1. So it would be str[1]

2. The parsing way

  str = Util.argsParser(str)

This will parse the args using a specific syntax. So "commandname first:hello,secound:just,third:testing" --> Object{first:"hello",secound:"just",third:"testing" }

3. The hybird method

Want to use both? Then use the splitpoint argument for argsParser. Like so

  var space = str.split(" ")
  var parsed = Util.argsParser(str,2) // index in which to begin parsing. Default is 1

If you want to learn more about commands, try figuring out this:

module.exports = function(str,main,log) { // name command
    str = str.split(" ") // get the arguments
var id = parseInt(str[1]) // id arg
var name = str.slice(2).join(" ") // join all the args after the second one so names with spaces work
if (isNaN(id) || !name) {
    log("Please provide the player id and name") // Require those arguments
    return
}
    var player = main.getPlayer(id) // get the player by his id
    if (!player) return log("No player with that id was found") // no such player exists!
   
    log("Changed player " + player.gameData.name + " to " + name) // log
         player.setName(name) // change the name
}

Adding gamemodes

A gamemode allows you to play the game differently. Creating a gamemode is easy. The gamemode system is designed just like Ogar's! Except, there are some differences

The data object

Instead of using different arguments in a function, only one variable is used to access all of them. This allows us to add more things we can put in, while keeping the api same. For example:

    onPlayerInit(data) { // Called when a player joins a server
    var player = data.player, // Player that joined.
        main = data.main, // server object. Every data variable has it.
        log = data.log // log function. Every data variable has it
    }

Return values

Returning false on most functions, will stop it's default action.

Including it in your plugin.

After you finished creating the gamemode, it is very easy to add it to your plugin. Just do this:

gamemodes: [require('./yourgamemode.js')]

Events

Events are one of the most important aspects of plugins. There is a variety of events. You use them by adding the eventname in your plugin.

module.exports = {
// [General]
name: "Example of events", // Name of plugin REQUIRED
author: "Andrews54757", // author REQUIRED
description: '', // Desciprtion
minVersion: '', // minimum version requirements (optional)
version:  '1.0.0', // version REQUIRED
addToHelp: false, // add to help
 commands: false, // commands
 configFile: false, //config file
// [Functions]
init: function (data,configs) {
  // init, Used to do stuff such as overriding things
},
// [Events]
onPlayerSpawn(data) {
var player = data.player
}
}

The data object

Instead of using different arguments in a function, only one variable is used to access all of them. This allows us to add more things we can put in, while keeping the api same. For example:

    onPlayerSpawn(data) { // Called when a player spawns
    var player = data.player, // Player that joined.
        main = data.main, // server object. Every data variable has it.
        log = data.log // log function. Every data variable has it
    }

Return values

Returning false on most functions, will stop it's default action.

List of events