one_command/Docs/Plugins.md

No longer maintained: please use www.npmjs.com/package/smelt-cli

* [Syntax](./Syntax.md)
* [BangCommands](./BangCommands.md)
* [Plugins](./Plugins.md)
* [Configuration](./Configuration.md)

Plugins
=======

Now one-command also supports plugins! These can be used to add to the 
available "bang commands" built into *one-command*.

Plugins need to be installed into a `/one-command/plugins/` directory alongside the .mcc files you plan on 
processing. 

You can see an example of this in the `demo` directory included in the git repository 
for this project. There is a `sayred.js` plugin in the `/one-command/plugins/` directory. 
You can see this being used in the `demo.mcc` file.

Plugins can also declare *setup* .mcc files that need to be installed into your map for the 
commands generated by the plugin to work correctly. 

***Warning:*** The work on plugins will continue and so the API for plugins is subject to 
change a lot in this early development.

----


Building a plugin
-----------------

Building a plugin is as easy as writing JavaScript. That's because they are written in JavaScript!

In addition, plugins are runin NodeJS, so you can also use any native node modules (such as 'util').

A basic plugin called `!sayred` would be written in a file called `sayred.js`. The code inside would be:

```
var util = require("util");

var sayred = function(args, addCommand, addSetup)
{			
	var message = args.join(" ");
	
    var command = "/tellraw @a [{\"text\":\"%s\",\"color\":\"red\"}]";
	
    addCommand(util.format(command, message));

	addSetup("sayred-setup.mcc");
}

module.exports = sayred;
```

Notice that the plugin calls two callback methods, `addCommand` and `addSetup`.

### addCommand(command, options)

The `addCommand` method can be used many times to create the Minecraft 
commands that your plugin generates. 

The first parameter is the `command` string. 

The second parameter is optional, and can take additional `options` for 
that command simular to the JSON options used in the `.mcc` syntax.

```
addCommand("/testfor Gnasp", {type:"repeating",auto:true,conditional:false});
```

### addSetup(filename)

The `addSetup` method is used to also tell *one-command* that for this plugin to work, 
another command module needs to be installed into the map. 

The file referenced has to be included alongside your JavaScript file.

```
addSetup("sayred-setup.mcc");
```