|
|
| (34 intermediate revisions by 2 users not shown) |
| Line 1: |
Line 1: |
| = Perl language prerequisites =
| | This page is now hosted on GitHub: [https://github.com/Yaribz/SPADS/wiki/SPADS-plugin-development SPADS plugin development] |
| | |
| 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 [http://search.cpan.org/~nine/Inline-Python-0.41/Python.pod 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 [http://perldoc.perl.org/5.14.1/perlintro.html this brief introduction to Perl].
| |
| | |
| = Simple plugin tutorial =
| |
| | |
| 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 [http://planetspads.free.fr/spads/plugins/templates/commented/ here], while the raw versions (without comment) are available [http://planetspads.free.fr/spads/plugins/templates/raw/ here].
| |
| | |
| Our first plugin will be very basic, so we will use the simplest template: "MySimplePlugin.pm". Let's download [http://planetspads.free.fr/spads/plugins/templates/commented/MySimplePlugin.pm 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 [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir 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 [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html 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 [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onPrivateMsg-userName-message- onPrivateMsg event-based callback].
| |
| | |
| We also want our plugin to send a private message, to do so we can call the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#sayPrivate-user-message- 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:
| |
| {|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
| |
| |
| |
| 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 [http://planetspads.free.fr/spads/plugins/tutorials/HelloWorld.pm 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...
| |
| | |
| [[Category:Autohosts]]
| |
