SPADS plugin development

Perl language prerequisites

SPADS is coded in Perl, and expects plugins coded in Perl. It should be possible to write plugins in other languages, using wrappers and modules such as Inline-Python for Python, but this tutorial will only speak about the simplest way to write SPADS plugins, which is using Perl.

SPADS plugins are object-oriented Perl modules. If you don't know Perl basics, you can take a look at this brief introduction to Perl.

Simple plugin tutorial (HelloWorld)

In this section we are going to write our first SPADS plugin. So let's start simple with a good old "Hello world". The plugin will answer "Hello World" to anyone saying "Hello" in a private message to SPADS.

Choosing our template

Some plugin templates are available to help you bootstrap your plugin development. The commented versions of these templates are available here, while the raw versions (without comment) are available here.

Our first plugin will be very basic, so we will use the simplest template: "MySimplePlugin.pm". Let's download the commented version of this template and open it with our favorite editor. As you can see, the code is heavily commented (actually every single line of code is explained), so I won't go into further details here. Now that you've read and understood the commented template, let's actually start plugin development.

Adapting the template

First we must name our plugin. Let's call it "HelloWorld". We have to rename the downloaded template from "MySimplePlugin.pm" to "HelloWorld.pm", and edit it to replace "MySimplePlugin" by "HelloWorld" in the source code.

Checking SPADS plugin system

Before going into actually writing new code, let's just check that the plugin works in SPADS (if not done yet, you have to configure the SPADS plugins directory in your spads.conf configuration file and reload SPADS configuration).

We have to move our new plugin (HelloWorld.pm) in the SPADS plugins directory so that SPADS can find it. Then, as a privileged SPADS user, we can type following command (in a private message to SPADS for example): "!plugin HelloWorld load". SPADS should answer "Loaded plugin HelloWorld.", which indicates the plugin has been loaded successfully.

If all is ok, we can let this SPADS instance running like this, we will get back to it later.

Writing plugin code

Writing plugin code mainly consists in implementing plugin callbacks and calling plugin API functions, as specified in SPADS plugin API documentation.

So we want our plugin to react to some private messages sent to SPADS. To do so we have to implement a plugin callback function which is called by SPADS core each time a lobby private message is received: this is the onPrivateMsg event-based callback.

We also want our plugin to send a private message, to do so we can call the plugin API function sayPrivate.

Now that we have identified the API functions that we need, we can actually implement our plugin. Here is a commented implementation example of the "onPrivateMsg" callback, which will answer "Hello World" to anyone saying "Hello" in a private message to SPADS:

sub onPrivateMsg { # $self is the plugin object (first parameter of all plugin callbacks) # $userName is the name of the user sending the private message # $message is the message sent by the user my ($self,$userName,$message)=@_; # We check the message sent by the user is "Hello" if($message eq 'Hello') { # We send our wonderful Hello World message sayPrivate($userName,'Hello World'); } # We return 0 because we don't want to filter out private messages # for other SPADS processing return 0; }

All we have to do now is adding this callback declaration in our HelloWorld.pm file located in SPADS plugins directory. We obtain this fully functional HelloWorld plugin.

Testing our plugin

Let's test this plugin in SPADS. First, since we modified the plugin source code, we have to tell SPADS to reload the plugin as follows: "!plugin HelloWorld reload". SPADS should answer "Reloaded plugin HelloWorld.", which indicates the plugin has been reloaded successfully.

Finally, just say "Hello" to SPADS in a private message. Congratulations for your first SPADS plugin! ;)

Configurable plugin tutorial

In progress...

New command plugin tutorial

In progress...