Plugin Tutorial

This guide will help you customize Weapon M by writing your first plugin. With a plugin, you can add new scripts or mouse overlays, with more functionality planned. A plugin is a directory or zip file containing a few things:

1. A plugin.yaml descriptor file
2. One or more JavaScript files

Prerequisites

This tutorial assumes you have installed Weapon M either from building the project from source or by using the installers:

• Windows
• OSX

You will also need to have located your Weapon M home directory:

• Windows - %APPDATA%/Weapon M
• OSX/Linux - $HOME/.weaponm

Step 1 - Create your plugin directory

First, you need to create the directory to contain your plugin files. Navigate to your Weapon M home directory and find the "plugins" directory. Create a directory in that "plugins" directory. For the purposes of the tutorial, let's assume your plugin will be named "myplugin".

Step 2 - Create the plugin descriptor

Next, you need to create a descriptor file called "plugin.yaml" that describes your plugin. The descriptor file should be created in your plugin directory. Here is a sample plugin descriptor:

#!yaml

name : My Plugin
description: My tutorial plugin

Step 3 - Write a script

At this point, you can create any type of plugin module, but for this tutorial, we're going to create a script. To create a plugin module, add a JavaScript file to the directory name matching the module, so in this case, we are going to create a script, so let's create a file called "Whos_Online.js" in the "script" sub-directory of our plugin.

"script/Whos_Online.js" will simply ask for the currently logged in players every time a command prompt is shown:

#!javascript
/**
 * Shows the currently logged in players on every command prompt
 *
 * @accelerator control W
 */
function onStart(script) {
    if (!script.isConnected()) {
        quit("Must be connected to run");
    }
}

function onCommandPrompt(seconds, sector) {
    send("#");
}

A few things to note about this script:

1. Each script should have a description at the top, though this is optional
2. The "@accelator" line is optional, but it allows our script to be invoked via a keyboard shortcut
3. The "onStart" method is called when our script is invoked. Here, we make sure Weapon M is actually connected to a game before continuing
4. The "onCommandPrompt" function is automatically registered to receive the script event COMMAND_PROMPT, as would any other function that begins with "on" and the rest matches another valid ScriptEvent value. Each script event passes a different set of arguments, but in this case, we recieve the number of seconds shown by the time and the current sector number.
5. The "send()" function call sends text to the game, in this case, a request for the current players

(Optional) Step 4 - Package your script for sharing

If you want to share your script, you can zip the plugin directory into a single zip file whos name matches the directory name. Therefore, for this plugin, we would create myplugin.zip This zip file can then be shared with other players and installed by copying the zip file to the player's "plugin" directory in their Weapon M home directory.

Success!

You now have successfully created your first plugin. Start Weapon M and your script should be recognized and available in the "Scripts" menu.

If you are the type of person that learns by example, take a look at the starter plugin that ships with Weapon M located in "plugins/starter" in your Weapon M directory. It contains scripts as well as other plugin modules such as overlay-detector and overlay-action.