Spring - User contributions [en]

SPADS plugin development (Python)

2024-07-15T10:08:22Z

Bibim: Replaced content with "This page is now hosted on GitHub: [https://github.com/Yaribz/SPADS/wiki/SPADS-plugin-development-(Python) SPADS plugin development (Python)]"

This page is now hosted on GitHub: [https://github.com/Yaribz/SPADS/wiki/SPADS-plugin-development-(Python) SPADS plugin development (Python)]

SPADS plugin development

2024-07-15T10:04:24Z

Bibim: Replaced content with "This page is now hosted on GitHub: [https://github.com/Yaribz/SPADS/wiki/SPADS-plugin-development SPADS plugin development]"

This page is now hosted on GitHub: [https://github.com/Yaribz/SPADS/wiki/SPADS-plugin-development SPADS plugin development]

SPADS plugin install notes

2024-07-15T10:02:33Z

Bibim: Replaced content with "This page is now hosted on GitHub: [https://github.com/Yaribz/SPADS/wiki/SPADS-plugin-install-notes SPADS plugin install notes]"

This page is now hosted on GitHub: [https://github.com/Yaribz/SPADS/wiki/SPADS-plugin-install-notes SPADS plugin install notes]

SPADS update procedure for new Spring version

2024-07-15T10:01:17Z

Bibim: Replaced content with "This page is now hosted on GitHub: [https://github.com/Yaribz/SPADS/wiki/SPADS-update-procedure-for-new-Spring-version SPADS update procedure for new Spring version]"

This page is now hosted on GitHub: [https://github.com/Yaribz/SPADS/wiki/SPADS-update-procedure-for-new-Spring-version SPADS update procedure for new Spring version]

SPADS official plugins list

2024-07-15T09:47:10Z

Bibim: Replaced content with "This page is now hosted on GitHub: [https://github.com/Yaribz/SPADS/wiki/SPADS-official-plugins-list SPADS official plugins list]"

This page is now hosted on GitHub: [https://github.com/Yaribz/SPADS/wiki/SPADS-official-plugins-list SPADS official plugins list]

SPADS

2024-07-15T09:38:48Z

Bibim:

== Support ==
*[https://github.com/Yaribz/SPADS/blob/master/INSTALL.md Installation]
*[https://springrts.com/phpbb/viewtopic.php?f=1&t=17130 Discussion in Spring forums]
*[https://github.com/Yaribz/SPADS/issues Issue tracker]

== Reference documents ==
*[http://planetspads.free.fr/spads/doc/spadsDoc.html Commands and settings reference guide]
*[http://planetspads.free.fr/spads/conf/templates/ Configuration templates]
*[https://github.com/Yaribz/SPADS/wiki/SPADS-official-plugins-list Official plugins list]

== Memos ==
*[https://github.com/Yaribz/SPADS/wiki/SPADS-update-procedure-for-new-Spring-version SPADS update procedure for new Spring version]
*[https://github.com/Yaribz/SPADS/blob/master/UPDATE.md Manual procedure for major SPADS update]
*[https://github.com/Yaribz/SPADS/wiki/SPADS-plugin-install-notes Plugin installation notes]
*[https://github.com/Yaribz/SPADS/wiki/Balancing-teams-on-a-LAN-server Balancing teams on a LAN server]

== Beyond All Reason specific ==
*[https://github.com/Yaribz/SPADS/wiki/Beyond-All-Reason-LAN-server-quick-install-guide-(Windows) Beyond All Reason LAN server quick install guide (Windows)]
*[https://github.com/Yaribz/SPADS/wiki/Beyond-All-Reason-LAN-server-quick-install-guide-(Linux) Beyond All Reason LAN server quick install guide (Linux)]
*[https://github.com/Yaribz/SPADS/wiki/Beyond-All-Reason-client-configuration-to-connect-to-a-LAN-server Beyond All Reason client configuration to connect to a LAN server]
*[https://github.com/Yaribz/SPADS/wiki/Beyond-All-Reason-LAN-server-customization Beyond All Reason LAN server customization]
*[https://github.com/Yaribz/SPADS/wiki/Beyond-All-Reason-offline-LAN-server-guide Beyond All Reason offline LAN server guide]

== Development ==
*[https://github.com/Yaribz/SPADS Source code]
*[http://planetspads.free.fr/spads/repository/CHANGELOG Detailed changelog]
*[http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html Plugin API documentation]
*[https://github.com/Yaribz/SPADS/wiki/SPADS-plugin-development Plugin development tutorials (Perl)]
*[https://github.com/Yaribz/SPADS/wiki/SPADS-plugin-development-(Python) Plugin development tutorials (Python)]

__NOTOC__
[[Category:Autohosts]]
[[Category:SPADS]]

SPADS

2024-07-15T09:32:35Z

Bibim:

SPADS links
----

== Support ==
*[https://github.com/Yaribz/SPADS/blob/master/INSTALL.md Installation]
*[https://springrts.com/phpbb/viewtopic.php?f=1&t=17130 Discussion in Spring forums]
*[https://github.com/Yaribz/SPADS/issues Issue tracker]

== Reference documents ==
*[http://planetspads.free.fr/spads/doc/spadsDoc.html Commands and settings reference guide]
*[http://planetspads.free.fr/spads/conf/templates/ Configuration templates]
*[https://github.com/Yaribz/SPADS/wiki/SPADS-official-plugins-list Official plugins list]

== Memos ==
*[https://github.com/Yaribz/SPADS/wiki/SPADS-update-procedure-for-new-Spring-version SPADS update procedure for new Spring version]
*[https://github.com/Yaribz/SPADS/blob/master/UPDATE.md Manual procedure for major SPADS update]
*[https://github.com/Yaribz/SPADS/wiki/SPADS-plugin-install-notes Plugin installation notes]
*[https://github.com/Yaribz/SPADS/wiki/Balancing-teams-on-a-LAN-server Balancing teams on a LAN server]

== Beyond All Reason specific ==
*[https://github.com/Yaribz/SPADS/wiki/Beyond-All-Reason-LAN-server-quick-install-guide-(Windows) Beyond All Reason LAN server quick install guide (Windows)]
*[https://github.com/Yaribz/SPADS/wiki/Beyond-All-Reason-LAN-server-quick-install-guide-(Linux) Beyond All Reason LAN server quick install guide (Linux)]
*[https://github.com/Yaribz/SPADS/wiki/Beyond-All-Reason-client-configuration-to-connect-to-a-LAN-server Beyond All Reason client configuration to connect to a LAN server]
*[https://github.com/Yaribz/SPADS/wiki/Beyond-All-Reason-LAN-server-customization Beyond All Reason LAN server customization]
*[https://github.com/Yaribz/SPADS/wiki/Beyond-All-Reason-offline-LAN-server-guide Beyond All Reason offline LAN server guide]

== Development ==
*[https://github.com/Yaribz/SPADS Source code]
*[http://planetspads.free.fr/spads/repository/CHANGELOG Detailed changelog]
*[http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html Plugin API documentation]
*[https://github.com/Yaribz/SPADS/wiki/SPADS-plugin-development Plugin development tutorials (Perl)]
*[https://github.com/Yaribz/SPADS/wiki/SPADS-plugin-development-(Python) Plugin development tutorials (Python)]

__NOTOC__
[[Category:Autohosts]]
[[Category:SPADS]]

SPADS Inline::Python installation guide

2024-03-16T11:19:51Z

Bibim:

= Introduction =

<code>Inline::Python</code> is a Perl module which allows interactions between Perl code and Python code. SPADS uses it to communicate with plugins coded in Python. This document will detail the different ways to install <code>Inline::Python</code> on Linux and Windows.

 
= Installing Inline::Python on Linux =
 
== Method 1: Using the package manager of your Linux distribution ==
This is the easiest way to install <code>Inline::Python</code> (if your distribution supports it), as it automatically downloads and installs a package specifically prepared for your distribution.

For this method you just need to find the name of the system package containing the <code>Inline::Python</code> Perl module and install it on your system. 
For example, for Debian based distributions: <code>apt-get install libinline-python-perl</code> 
For Red Hat based distributions: <code>dnf install perl-Inline-Python</code>

 
== Method 2: Using cpan ==
<code>cpan</code> is the standard tool included with Perl to install modules from the [https://www.cpan.org/ Comprehensive Perl Archive Network].

To install the latest stable release of <code>Inline::Python</code> using <code>cpan</code>, enter following command (with root privileges if you are using the system Perl): 
<code>cpan Inline::Python</code>

 
= Installing Inline::Python on Windows =
 
To install the latest stable release of <code>Inline::Python</code> using <code>cpanminus</code>, enter following command: 
<code><nowiki>cpanm Inline::Python</nowiki></code>

SPADS official plugins list

2024-02-26T22:00:39Z

Bibim:

This page lists all official SPADS plugins, with basic descriptions (more information is usually available in the README file of the plugin). Refer to [http://springrts.com/wiki/SPADS_plugin_install_notes SPADS plugin install notes] for installation instructions.

== [http://planetspads.free.fr/spads/plugins/AutoPauseOnVote.pm AutoPauseOnVote] ==
automatically pauses the game when a vote is called

== [http://planetspads.free.fr/spads/plugins/AutoRegister.zip AutoRegister] ==
automatically registers the lobby account used by SPADS if needed

== [http://planetspads.free.fr/spads/plugins/AutoSpec.zip AutoSpec] ==
automatically warns/specs unsync/unready players with configurable delays and thresholds

== [http://planetspads.free.fr/spads/plugins/BarAutoUpdate.zip BarAutoUpdate] ==
auto-update and auto-reload functionalities for various Beyond All Reason components

== [http://planetspads.free.fr/spads/plugins/BarChobby.zip BarChobby] ==
lobby protocol extension to allow BAR Chobby to display some SPADS settings in the GUI

== [http://planetspads.free.fr/spads/plugins/ClientStatusEvents.zip ClientStatusEvents] ==
extends the plugin API with new event-based callbacks on client status changes

== [http://planetspads.free.fr/spads/plugins/ClusterManager.zip ClusterManager] ==
turns a SPADS instance into a manager of clusters of SPADS instances

== [http://planetspads.free.fr/spads/plugins/CustomAliases.zip CustomAliases] ==
makes it possible to define your own aliases for all SPADS commands

== [http://planetspads.free.fr/spads/plugins/CustomTeamColors.zip CustomTeamColors] ==
makes it possible to customize the team colors applied by SPADS

== [http://planetspads.free.fr/spads/plugins/DownloadArchives.zip DownloadArchives] ==
adds !dlmap and !dlmod commands for map and mod downloads

== [http://planetspads.free.fr/spads/plugins/DynamicMapRotation.zip DynamicMapRotation] ==
changes rotation map list automatically according to battle context

== [http://planetspads.free.fr/spads/plugins/FirstWelcomeMsg.zip FirstWelcomeMsg] ==
sends a message to a player the first time he joins the battle only

== [http://planetspads.free.fr/spads/plugins/InGameMute.zip InGameMute] ==
adds !mute, !unmute and !mutes commands for in-game mutes

== [http://planetspads.free.fr/spads/plugins/LanServer.zip LanServer] ==
implements a lobby server running in LAN mode (allows SPADS to operate autonomously)

== [http://planetspads.free.fr/spads/plugins/PreventVoteExploit.zip PreventVoteExploit] ==
tries to prevent vote exploits using multi accounts

== [http://planetspads.free.fr/spads/plugins/RecommendedMap.zip RecommendedMap] ==
chooses map automatically depending on game type and number of players

== [http://planetspads.free.fr/spads/plugins/RequiredChannel.zip RequiredChannel] ==
forces players to be in a channel before being able to join the battle

== [http://planetspads.free.fr/spads/plugins/Resign.zip Resign] ==
adds !resign command and specific vote system to resign as a team

== [http://planetspads.free.fr/spads/plugins/ReverseLookup.zip ReverseLookup] ==
shows hostnames near IP addresses in !status output

== [http://planetspads.free.fr/spads/plugins/SpringieExtension.zip SpringieExtension] ==
implements Springie/Zero-K lobby protocol extension

== [http://planetspads.free.fr/spads/plugins/ZeroK.zip ZeroK] ==
implements Zero-K specific functionalities

__NOTOC__
[[Category:SPADS]]

SPADS official plugins list

2024-02-26T21:43:50Z

Bibim:

This page lists all official SPADS plugins, with basic descriptions (more information is usually available in the README file of the plugin). Refer to [http://springrts.com/wiki/SPADS_plugin_install_notes SPADS plugin install notes] for installation instructions.

== [http://planetspads.free.fr/spads/plugins/AutoPauseOnVote.pm AutoPauseOnVote] ==
automatically pauses the game when a vote is called

== [http://planetspads.free.fr/spads/plugins/AutoRegister.zip AutoRegister] ==
automatically registers the lobby account used by SPADS if needed

== [http://planetspads.free.fr/spads/plugins/AutoSpec.zip AutoSpec] ==
automatically warns/specs unsync/unready players with configurable delays and thresholds

== [http://planetspads.free.fr/spads/plugins/BarAutoUpdate.zip BarAutoUpdate] ==
auto-update and auto-reload functionalities for various Beyond All Reason components

== [http://planetspads.free.fr/spads/plugins/BarChobby.zip BarChobby] ==
lobby protocol extension to allow BAR Chobby to display some SPADS settings in the GUI

== [http://planetspads.free.fr/spads/plugins/ClientStatusEvents.zip ClientStatusEvents] ==
extends the plugin API with new event-based callbacks on client status changes

== [http://planetspads.free.fr/spads/plugins/ClusterManager.zip ClusterManager] ==
turns a SPADS instance into a manager of clusters of SPADS instances

== [http://planetspads.free.fr/spads/plugins/CustomAliases.zip CustomAliases] ==
makes it possible to define your own aliases for all SPADS commands

== [http://planetspads.free.fr/spads/plugins/CustomTeamColors.zip CustomTeamColors] ==
makes it possible to customize the team colors applied by SPADS

== [http://planetspads.free.fr/spads/plugins/DownloadArchives.zip DownloadArchives] ==
adds !dlmap and !dlmod commands for map and mod downloads

== [http://planetspads.free.fr/spads/plugins/DynamicMapRotation.zip DynamicMapRotation] ==
changes rotation map list automatically according to battle context

== [http://planetspads.free.fr/spads/plugins/FirstWelcomeMsg.zip FirstWelcomeMsg] ==
sends a message to a player the first time he joins the battle only

== [http://planetspads.free.fr/spads/plugins/InGameMute.zip InGameMute] ==
adds !mute, !unmute and !mutes commands for in-game mutes

== [http://planetspads.free.fr/spads/plugins/PreventVoteExploit.zip PreventVoteExploit] ==
tries to prevent vote exploits using multi accounts

== [http://planetspads.free.fr/spads/plugins/RecommendedMap.zip RecommendedMap] ==
chooses map automatically depending on game type and number of players

== [http://planetspads.free.fr/spads/plugins/RequiredChannel.zip RequiredChannel] ==
forces players to be in a channel before being able to join the battle

== [http://planetspads.free.fr/spads/plugins/Resign.zip Resign] ==
adds !resign command and specific vote system to resign as a team

== [http://planetspads.free.fr/spads/plugins/ReverseLookup.zip ReverseLookup] ==
shows hostnames near IP addresses in !status output

== [http://planetspads.free.fr/spads/plugins/SpringieExtension.zip SpringieExtension] ==
implements Springie/Zero-K lobby protocol extension

== [http://planetspads.free.fr/spads/plugins/ZeroK.zip ZeroK] ==
implements Zero-K specific functionalities

__NOTOC__
[[Category:SPADS]]

SPADS official plugins list

2024-02-26T21:28:03Z

Bibim:

This page lists all official SPADS plugins, with basic descriptions (more information is usually available in the README file of the plugin). Refer to [http://springrts.com/wiki/SPADS_plugin_install_notes SPADS plugin install notes] for installation instructions.

== [http://planetspads.free.fr/spads/plugins/AutoPauseOnVote.pm AutoPauseOnVote] ==
automatically pauses the game when a vote is called

== [http://planetspads.free.fr/spads/plugins/AutoRegister.zip AutoRegister] ==
automatically registers the lobby account used by SPADS if needed

== [http://planetspads.free.fr/spads/plugins/AutoSpec.zip AutoSpec] ==
automatically warns/specs unsync/unready players with configurable delays and thresholds

== [http://planetspads.free.fr/spads/plugins/BarChobby.zip BarChobby] ==
lobby protocol extension to allow BAR Chobby to display some SPADS settings in the GUI

== [http://planetspads.free.fr/spads/plugins/ClientStatusEvents.zip ClientStatusEvents] ==
extends the plugin API with new event-based callbacks on client status changes

== [http://planetspads.free.fr/spads/plugins/ClusterManager.zip ClusterManager] ==
turns a SPADS instance into a manager of clusters of SPADS instances

== [http://planetspads.free.fr/spads/plugins/CustomAliases.zip CustomAliases] ==
makes it possible to define your own aliases for all SPADS commands

== [http://planetspads.free.fr/spads/plugins/CustomTeamColors.zip CustomTeamColors] ==
makes it possible to customize the team colors applied by SPADS

== [http://planetspads.free.fr/spads/plugins/DownloadArchives.zip DownloadArchives] ==
adds !dlmap and !dlmod commands for map and mod downloads

== [http://planetspads.free.fr/spads/plugins/DynamicMapRotation.zip DynamicMapRotation] ==
changes rotation map list automatically according to battle context

== [http://planetspads.free.fr/spads/plugins/FirstWelcomeMsg.zip FirstWelcomeMsg] ==
sends a message to a player the first time he joins the battle only

== [http://planetspads.free.fr/spads/plugins/InGameMute.zip InGameMute] ==
adds !mute, !unmute and !mutes commands for in-game mutes

== [http://planetspads.free.fr/spads/plugins/PreventVoteExploit.zip PreventVoteExploit] ==
tries to prevent vote exploits using multi accounts

== [http://planetspads.free.fr/spads/plugins/RecommendedMap.zip RecommendedMap] ==
chooses map automatically depending on game type and number of players

== [http://planetspads.free.fr/spads/plugins/RequiredChannel.zip RequiredChannel] ==
forces players to be in a channel before being able to join the battle

== [http://planetspads.free.fr/spads/plugins/Resign.zip Resign] ==
adds !resign command and specific vote system to resign as a team

== [http://planetspads.free.fr/spads/plugins/ReverseLookup.zip ReverseLookup] ==
shows hostnames near IP addresses in !status output

== [http://planetspads.free.fr/spads/plugins/SpringieExtension.zip SpringieExtension] ==
implements Springie/Zero-K lobby protocol extension

== [http://planetspads.free.fr/spads/plugins/ZeroK.zip ZeroK] ==
implements Zero-K specific functionalities

__NOTOC__
[[Category:SPADS]]

SPADS

2023-06-14T08:02:15Z

Bibim: /* Memos */

SPADS

2023-06-14T07:58:14Z

Bibim:

SPADS PerlUnitSync module generation for Windows

2023-06-14T07:57:35Z

Bibim: remove obsolete information

SPADS:Installation

2023-06-14T07:51:59Z

Bibim: Remove obsolete information

SPADS official plugins list

2021-10-25T21:54:19Z

Bibim:

This page lists all official SPADS plugins, with basic descriptions (more information is usually available in the README file of the plugin). Refer to [http://springrts.com/wiki/SPADS_plugin_install_notes SPADS plugin install notes] for installation instructions.

== [http://planetspads.free.fr/spads/plugins/AutoPauseOnVote.pm AutoPauseOnVote] ==
automatically pauses the game when a vote is called

== [http://planetspads.free.fr/spads/plugins/AutoRegister.zip AutoRegister] ==
automatically registers the lobby account used by SPADS if needed

== [http://planetspads.free.fr/spads/plugins/AutoSpec.zip AutoSpec] ==
automatically warns/specs unsync/unready players with configurable delays and thresholds

== [http://planetspads.free.fr/spads/plugins/ClientStatusEvents.zip ClientStatusEvents] ==
extends the plugin API with new event-based callbacks on client status changes

== [http://planetspads.free.fr/spads/plugins/ClusterManager.zip ClusterManager] ==
turns a SPADS instance into a manager of clusters of SPADS instances

== [http://planetspads.free.fr/spads/plugins/CustomAliases.zip CustomAliases] ==
makes it possible to define your own aliases for all SPADS commands

== [http://planetspads.free.fr/spads/plugins/CustomTeamColors.zip CustomTeamColors] ==
makes it possible to customize the team colors applied by SPADS

== [http://planetspads.free.fr/spads/plugins/DownloadArchives.zip DownloadArchives] ==
adds !dlmap and !dlmod commands for map and mod downloads

== [http://planetspads.free.fr/spads/plugins/DynamicMapRotation.zip DynamicMapRotation] ==
changes rotation map list automatically according to battle context

== [http://planetspads.free.fr/spads/plugins/FirstWelcomeMsg.zip FirstWelcomeMsg] ==
sends a message to a player the first time he joins the battle only

== [http://planetspads.free.fr/spads/plugins/InGameMute.zip InGameMute] ==
adds !mute, !unmute and !mutes commands for in-game mutes

== [http://planetspads.free.fr/spads/plugins/PreventVoteExploit.zip PreventVoteExploit] ==
tries to prevent vote exploits using multi accounts

== [http://planetspads.free.fr/spads/plugins/RecommendedMap.zip RecommendedMap] ==
chooses map automatically depending on game type and number of players

== [http://planetspads.free.fr/spads/plugins/RequiredChannel.zip RequiredChannel] ==
forces players to be in a channel before being able to join the battle

== [http://planetspads.free.fr/spads/plugins/Resign.zip Resign] ==
adds !resign command and specific vote system to resign as a team

== [http://planetspads.free.fr/spads/plugins/ReverseLookup.zip ReverseLookup] ==
shows hostnames near IP addresses in !status output

== [http://planetspads.free.fr/spads/plugins/SpringieExtension.zip SpringieExtension] ==
implements Springie/Zero-K lobby protocol extension

== [http://planetspads.free.fr/spads/plugins/ZeroK.zip ZeroK] ==
implements Zero-K specific functionalities

__NOTOC__
[[Category:SPADS]]

SPADS Inline::Python installation guide

2021-10-05T07:07:13Z

Bibim: /* Method 1: Using cpanminus to install latest version from GitHub */

= Introduction =

<code>Inline::Python</code> is a Perl module which allows interactions between Perl code and Python code. SPADS uses it to communicate with plugins coded in Python.

Unfortunately the current stable release of this module suffers from a bug which makes Perl strings appear as byte strings when used with Python 3 (Python 2 is unaffected). This is not a blocking problem, as Python can easily convert these data if needed and SPADS plugin API offers dedicated functions to deal with the problem (cf the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#Perl-strings-conversions PYTHON SPECIFIC NOTES - Perl strings conversions] section of the Plugin API documentation). However, a cleaner way to solve this problem is to install a fixed version of the module, directly from the official module maintainer repository. The remaining of this document will detail the different ways to install <code>Inline::Python</code>, on Linux and Windows.

 
= Installing Inline::Python on Linux =
 
== Method 1: Using cpanminus to install latest version from GitHub ==
<code>cpanminus</code> is a lightweight package manager for Perl, which is able to install Perl modules directly from Git repositories. This is very useful for <code>Inline::Python</code> installation because only the latest version from the module maintainer repository includes the fix for Perl string conversions with Python 3.

The first step consists in installing <code>cpanminus</code> (if not already installed on your system). To do that you can usually use the package manager of your Linux distribution. For example, for Debian based distributions: <code>apt-get install cpanminus</code>, or for Red Hat based distributions: <code>dnf install perl-App-cpanminus</code> (for other cases, check [https://metacpan.org/pod/App::cpanminus#INSTALLATION the INSTALLATION section of cpanminus documentation]).

In order to be able to install Perl package directly from Git repositories, Git must also be installed on the system. This can be done using following command for example on Debian based distributions: <code>apt-get install git</code>

Finally, building the <code>Inline::Python</code> module requires having Python headers available on the system, as well as the <code>distutils</code> Python package. You can install them using following command for example on Debian based distributions: <code>apt-get install python3-dev python3-distutils</code>

Once <code>cpanminus</code> and the dependencies are installed, <code>cpanminus</code> can be used to install the latest version of <code>Inline::Python</code> from module maintainer's repository. This can be done simply by entering following command (with root privileges if you are using the system Perl): 
<code><nowiki>cpanm https://github.com/niner/inline-python-pm.git</nowiki></code>

 

== Method 2: Using the package manager of your Linux distribution ==
This is the easiest way to install <code>Inline::Python</code> (if your distribution supports it), as it automatically downloads and installs a package specifically prepared for your distribution. However, this method installs the stable release of <code>Inline::Python</code>, which suffers from the string conversion bug with Python 3 explained in introduction. So this method is only recommended if you don't plan to use Python 3 or if the installation method based on <code>cpanminus</code> failed.

For this method you just need to find the name of the system package containing the <code>Inline::Python</code> Perl module and install it on your system. 
For example, for Debian based distributions: <code>apt-get install libinline-python-perl</code> 
For Red Hat based distributions: <code>dnf install perl-Inline-Python</code>

 
== Method 3: Using cpan ==
<code>cpan</code> is the standard tool included with Perl to install modules from the [https://www.cpan.org/ Comprehensive Perl Archive Network]. Unfortunately, only the current stable releases of the modules can easily be installed this way, so this method should only be reserved to cases where all other installation methods failed.

To install <code>Inline::Python</code> using <code>cpan</code>, simply enter following command (with root privileges if you are using the system Perl): 
<code>cpan Inline::Python</code>

 
= Installing Inline::Python on Windows =
 
== Step 1: Installing cpanminus ==
<code>cpanminus</code> is a lightweight module manager for Perl, which is able to install Perl modules directly from Git repositories and allows interactive mode installations.

If your are using Strawberry Perl, <code>cpanminus</code> should be pre-installed (you can check it by trying the <code>cpanm</code> command in a console windows). If you are using another Perl distribution and <code>cpanminus</code> isn't pre-installed, you should be able to use the packet manager of your Perl distribution (<code>ppm</code> for example for old ActiveState Perl releases) to install <code>cpanminus</code>. You can also use the generic default Perl module manager <code>cpan</code> to install it using following command: <code>cpan cpanminus</code>

 
== Step 2: Using cpanminus to install Inline::Python ==
As explained in introduction, the current stable release of <code>Inline::Python</code> suffers from the string conversion bug with Python 3, so it is recommended to install the latest version instead. Unfortunately, the installation script included in the latest version on the module maintainer repository has some problems when installing on Windows. I created my own fork on GitHub to fix these installation problems. As long as the module maintainer didn't merge my fixes in his repository, I recommend using my fork to install the latest version of <code>Inline::Python</code> on Windows, using following command: 
<code><nowiki>cpanm https://github.com/Yaribz/inline-python-pm.git</nowiki></code>

 
If for some reason the installation of the latest version of <code>Inline::Python</code> fails, you can try to install the stable release instead. Unfortunately, the current stable release of <code>Inline::Python</code> doesn't install automatically on Windows due to broken Python installation detection and one test which is coded for Linux system only and which must be skipped. Consequently, <code>cpanminus</code> must be run in interactive mode and with a flag to force installation despite the failing test, using this command: 
<code>cpanm --interactive -f Inline::Python</code>

The install script will then ask 4 questions:
# <code>Use which? [1]</code> Here you must enter the full path of your <code>python.exe</code> file from your Python installation (warning: paths containing spaces are not supported by the installer). For example: <code>C:\Python\python.exe</code>
# <code>Enter extra libraries (e.g. -lfoo -lbar) [None]</code> Here you can press enter, as no additional library should be needed for standard Python installation.
# <code>Which? Or enter another. [1]</code> Here you need to enter the digit corresponding to the library with 2 digits in its name. For example: <code>2</code> (to select entry <code>2) C:/Python/libs/python39.lib</code>)
# <code>Which? Or enter another. [1]</code> Here you can press enter as the install script should have auto-detected the include location of your Python installation correctly.

SPADS official plugins list

2021-03-30T20:23:46Z

Bibim:

This page lists all official SPADS plugins, with basic descriptions (more information is usually available in the README file of the plugin). Refer to [http://springrts.com/wiki/SPADS_plugin_install_notes SPADS plugin install notes] for installation instructions.

== [http://planetspads.free.fr/spads/plugins/AutoPauseOnVote.pm AutoPauseOnVote] ==
automatically pauses the game when a vote is called

== [http://planetspads.free.fr/spads/plugins/AutoRegister.zip AutoRegister] ==
automatically registers the lobby account used by SPADS if needed

== [http://planetspads.free.fr/spads/plugins/AutoSpec.zip AutoSpec] ==
automatically warns/specs unsync/unready players with configurable delays and thresholds

== [http://planetspads.free.fr/spads/plugins/ClusterManager.zip ClusterManager] ==
turns a SPADS instance into a manager of clusters of SPADS instances

== [http://planetspads.free.fr/spads/plugins/CustomAliases.zip CustomAliases] ==
makes it possible to define your own aliases for all SPADS commands

== [http://planetspads.free.fr/spads/plugins/CustomTeamColors.zip CustomTeamColors] ==
makes it possible to customize the team colors applied by SPADS

== [http://planetspads.free.fr/spads/plugins/DownloadArchives.zip DownloadArchives] ==
adds !dlmap and !dlmod commands for map and mod downloads

== [http://planetspads.free.fr/spads/plugins/DynamicMapRotation.zip DynamicMapRotation] ==
changes rotation map list automatically according to battle context

== [http://planetspads.free.fr/spads/plugins/FirstWelcomeMsg.zip FirstWelcomeMsg] ==
sends a message to a player the first time he joins the battle only

== [http://planetspads.free.fr/spads/plugins/InGameMute.zip InGameMute] ==
adds !mute, !unmute and !mutes commands for in-game mutes

== [http://planetspads.free.fr/spads/plugins/PreventVoteExploit.zip PreventVoteExploit] ==
tries to prevent vote exploits using multi accounts

== [http://planetspads.free.fr/spads/plugins/RecommendedMap.zip RecommendedMap] ==
chooses map automatically depending on game type and number of players

== [http://planetspads.free.fr/spads/plugins/RequiredChannel.zip RequiredChannel] ==
forces players to be in a channel before being able to join the battle

== [http://planetspads.free.fr/spads/plugins/Resign.zip Resign] ==
adds !resign command and specific vote system to resign as a team

== [http://planetspads.free.fr/spads/plugins/ReverseLookup.zip ReverseLookup] ==
shows hostnames near IP addresses in !status output

== [http://planetspads.free.fr/spads/plugins/SpringieExtension.zip SpringieExtension] ==
implements Springie/Zero-K lobby protocol extension

== [http://planetspads.free.fr/spads/plugins/ZeroK.zip ZeroK] ==
implements Zero-K specific functionalities

__NOTOC__
[[Category:SPADS]]

SPADS plugin development (Python)

2021-01-28T14:24:25Z

Bibim:

= Introduction =

SPADS is an autohost system coded in Perl, it supports both Perl and Python plugins. This tutorial deals with Python plugin development only (for Perl plugin development another tutorial is available [https://springrts.com/wiki/SPADS_plugin_development here]).

SPADS plugins are object-oriented modules. It is strongly recommended to already know Python basics before starting Python plugin development (a Python tutorial is available [https://docs.python.org/3/tutorial/ here]).

 
= Technical prerequisites =

Python (the Python interpreter and its libraries) must be installed on the system (versions 2.6+ or 3.2+ recommended). The type of installation (32-bit / 64-bit) must be consistent with the Perl version and the Spring engine used for SPADS.

Additionally, in order to allow communication between Perl code (SPADS core) and Python code (SPADS plugins), SPADS uses a Perl module named <code>Inline::Python</code> which must also be installed on the system. It is recommended to install the latest version for SPADS, refer to [https://springrts.com/wiki/SPADS_Inline::Python_installation_guide this guide] for installation.

 

= 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 [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] (the <code>.pm</code> files must be ignored for this tutorial, these are the Perl versions of the templates).

Our first plugin will be very basic, so we will use the simplest template: <code>mysimpleplugin.py</code>. Let's download [http://planetspads.free.fr/spads/plugins/templates/commented/mysimpleplugin.py 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 <code>HelloWorld</code>. We have to rename the downloaded template from <code>mysimpleplugin.py</code> to <code>helloworld.py</code>, and edit it to replace <code>MySimplePlugin</code> by <code>HelloWorld</code> 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 <code>spads.conf</code> configuration file and reload SPADS configuration).

We have to move our new plugin (<code>helloworld.py</code>) 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): <code>!plugin HelloWorld load</code>. SPADS should answer <code>Loaded plugin HelloWorld.</code>, 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-self-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 <code>onPrivateMsg</code> callback, which will answer <code>Hello World</code> to anyone saying <code>Hello</code> in a private message to SPADS:
<syntaxhighlight lang="python">
# This is the callback called each time SPADS receives a private message
# 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
def onPrivateMsg(self,userName,message):

# Here we "fix" strings received from Perl in case
# the Inline::Python module transmits them as byte strings
(userName,message)=spads.fix_string(userName,message)

# We check the message sent by the user is "Hello"
if message == 'Hello':

# We send our wonderful Hello World message
spads.sayPrivate(userName,'Hello World')

# We return 0 because we don't want to filter out private messages
# for other SPADS processing
return 0</syntaxhighlight>

All we have to do now is adding this callback declaration in our <code>helloworld.py</code> file located in SPADS plugins directory. We obtain [http://planetspads.free.fr/spads/plugins/tutorials/helloworld.py 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: <code>!plugin HelloWorld reload</code>. SPADS should answer <code>Reloaded plugin HelloWorld.</code>, which indicates the plugin has been reloaded successfully.

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

 
= Configurable plugin tutorial (ForbiddenWords) =

In this section we are going to write our first configurable SPADS plugin (a configurable plugin has its own configuration file, named after the plugin name but with <code>.conf</code> extension). This plugin will monitor all messages said by players in the battle lobby, and will kick players who use swear words.

== Specifying our configuration parameters ==

The first step of writing a configurable plugin is to choose how we will configure it. In our example, we will use 2 configuration parameters: <code>words</code> will contain the list of forbidden words, and <code>immuneLevel</code> will contain the minimum autohost access level to be immune regarding these forbidden words checks.

We choose to make <code>words</code> a global setting (unmodifiable, not impacted by preset change), and <code>immuneLevel</code> a preset setting (modifiable, can be impacted by preset change). The <code>words</code> global setting will have no restriction (can be empty, can contain any character...), whereas the <code>immuneLevel</code> preset setting will only be allowed to be an integer or integer range.

== Preparing the template ==

Once we have a clear view of our configuration settings, we can start adapting the template for our needs. Since we are making a configurable plugin, this time we will download [http://planetspads.free.fr/spads/plugins/templates/commented/myconfigurableplugin.py the configurable plugin template] and its associated [http://planetspads.free.fr/spads/plugins/templates/commented/MyConfigurablePlugin.conf configuration file example].

First, let's take a look at the configuration file example. This is a just a basic configuration file containing one global setting example and one preset setting example. Let's modify this file to match the configuration we chose as follows (don't forget to rename the file from <code>MyConfigurablePlugin.conf</code> to <code>ForbiddenWords.conf</code> also):
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# This is our global setting (can't be changed without reloading the configuration)
words:ass;asshole;bastard;bitch;cunt;fuck;motherfucker;shit;whore

# We must define our preset setting in the default preset at least
[default]

# This is our preset setting, which can be changed with "!plugin ... set ..."
# or by loading a preset.
# "100" is the default value, and any integer between 0 and 140 is allowed
immuneLevel:100|0-140
|}
Then we must prepare the plugin template itself, by renaming it from <code>myconfigurableplugin.py</code> to <code>forbiddenwords.py</code> and editing it to replace <code>MyConfigurablePlugin</code> by <code>ForbiddenWords</code> in the source code. We must also adapt the template so that it uses the configuration settings we chose. This is done by modifying the <code>globalPluginParams</code> and <code>presetPluginParam</code> declarations as follows:
<syntaxhighlight lang="python">
# We define one global setting "words" and one preset setting "immuneLevel".
# "words" has no type associated (no restriction on allowed values)
# "immuneLevel" must be an integer or an integer range
# (check %paramTypes hash in SpadsConf.pm for a complete list of allowed
# setting types)
globalPluginParams = { 'words': [] }
presetPluginParams = { 'immuneLevel': ['integer','integerRange'] }
</syntaxhighlight>

== Writing plugin code ==

We want our plugin to react to messages said in the battle lobby. There is no dedicated callback for this event in [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html SPADS plugin API documentation], so we have to set up our own handler on the [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#SAIDBATTLE:server SAIDBATTLE lobby command]. To do so we have to call the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addLobbyCommandHandler-handlers-priority-caller addLobbyCommandHandler]. We will call this function at the end of our plugin constructor as follows, so that it will be set up directly when the plugin is loaded:
<syntaxhighlight lang="python">
[...]

# We set up a lobby command handler on SAIDBATTLE
spads.addLobbyCommandHandler({'SAIDBATTLE': hLobbySaidBattle})
</syntaxhighlight>
However, if SPADS is disconnected from the lobby due to network problems for example, all lobby handlers are automatically removed. So we must re-add them each time we connect to lobby server. This can be done using the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onLobbyConnected-self-lobbyInterface onLobbyConnected] event-based callback as follows:
<syntaxhighlight lang="python">
# This callback is called each time we (re)connect to the lobby server
def onLobbyConnected(self,lobbyInterface):

# When we are disconnected from the lobby server, all lobby command
# handlers are automatically removed, so we (re)set up our command
# handler here.
spads.addLobbyCommandHandler({'SAIDBATTLE': hLobbySaidBattle})
</syntaxhighlight>
Also, it is a good practice to remove any handler we have added when the plugin is unloaded. To do so we must implement the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback as follows:
<syntaxhighlight lang="python">
# This callback is called when the plugin is unloaded
def onUnload(self,reason):

# We remove our lobby command handler when the plugin is unloaded
spads.removeLobbyCommandHandler(['SAIDBATTLE'])
</syntaxhighlight>
Finally, we have to implement our <code>SAIDBATTLE</code> handler <code>hLobbySaidBattle</code>. In this handler we need to perform following operations:
* skip processing if the user is the autohost itself: we need to access SPADS configuration to compare the user name with the [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:lobbyLogin lobbyLogin] setting value. So we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getSpadsConf getSpadsConf].
* perform processing according to our configuration (<code>words</code> and <code>immuneLevel</code> settings): we need to access our plugin configuration, so we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getPluginConf-pluginName-caller getPluginConf].
* retrieve the autohost access level of the user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getUserAccessLevel-user getUserAccessLevel]
* send a message to the battle lobby when we kick someone: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#sayBattle-message sayBattle].
* send a [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#KICKFROMBATTLE:client KICKFROMBATTLE] lobby command to kick a user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#queueLobbyCommand-lobbyCommand queueLobbyCommand].

Here is a commented implementation example of this <code>hLobbySaidBattle</code> handler, which will kick any non-privileged user saying a forbidden word in the battle lobby:
<syntaxhighlight lang="python">
# This is the handler we set up on SAIDBATTLE lobby command.
# It is called each time a player says something in the battle lobby.
# command is the lobby command name (SAIDBATTLE)
# user is the name of the user who said something in the battle lobby
# message is the message said in the battle lobby
def hLobbySaidBattle(command,user,message):

# First we "fix" strings received from Perl in case
# the Inline::Python module transmits them as byte strings
(user,message)=spads.fix_string(user,message)

# Here we check it's not a message from SPADS (so we don't kick ourself)
spadsConf = spads.getSpadsConf()
if user == spadsConf['lobbyLogin']:
return

# Then we check the user isn't a privileged user
# (autohost access level >= immuneLevel)
pluginConf = spads.getPluginConf()
if int(spads.getUserAccessLevel(user)) >= int(pluginConf['immuneLevel']):
return

# We put the forbidden words in a list
forbiddenWords = pluginConf['words'].split(';')

# We test each forbidden word
for forbiddenWord in forbiddenWords:

# If the message contains the forbidden word (case insensitive)
if re.search(r'\b' + re.escape(forbiddenWord) + r'\b',message,re.IGNORECASE):

# Then we kick the user from the battle lobby
spads.sayBattle("Kicking %s from battle (watch your language!)" % user)
spads.queueLobbyCommand(["KICKFROMBATTLE",user])

# We quit the foreach loop (no need to test other forbidden word)
break
</syntaxhighlight>

As we are using regular expressions in our plugin code, we must not forget to import the <code>re</code> Python module at the start of our plugin:
<syntaxhighlight lang="python">
# Import the regular expression module to check for forbidden words
import re
</syntaxhighlight>
Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/forbiddenwords.py this fully functional ForbiddenWords] plugin and [http://planetspads.free.fr/spads/plugins/tutorials/ForbiddenWords.conf its associated configuration file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the associated configuration file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: <code>!plugin ForbiddenWords load</code>. And finally, as an unprivileged user we can try to say some forbidden words in the battle lobby and we should get kicked by the plugin.

 

= New-command plugin tutorial (TimePlugin) =

In this section we are going to write a plugin which implements a new command for SPADS. Such plugins are configurable plugins like the one we wrote just before, with 2 additional files to configure the new commands. This plugin will give current time when someone types <code>!time</code>.

== Preparing the template ==

This time we need to download 4 files to prepare our plugin: [http://planetspads.free.fr/spads/plugins/templates/commented/mynewcommandplugin.py the new-command plugin template], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPlugin.conf the associated configuration file example], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginHelp.dat the help file example] and [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginCmd.conf the commands rights configuration file example].

As usual, we rename these files to match our plugin name: <code>MyNewCommandPlugin</code> --> <code>TimePlugin</code>. Then we edit the plugin template <code>timeplugin.py</code> and replace <code>MyNewCommandPlugin</code> by <code>TimePlugin</code> in the source code, and we do the same for the plugin configuration template <code>TimePlugin.conf</code>, so that the <code>commandsFile</code> and <code>helpFile</code> settings are consistent with the files we just renamed.

Then we can edit our command rights requirements configuration file: <code>TimePluginCmd.conf</code>. This file uses the same syntax as the standard SPADS <code>commands.conf</code> file. The template provides a default command <code>myCommand</code> with no requirement. We will just rename this command to <code>time</code>:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# Anyone can call our command from anywhere
[time]
::|0:
|}
Now we need to write the help information for our new command. This is done in the file <code>TimePluginHelp.dat</code>. This file uses the same syntax as the standard SPADS <code>help.dat</code> file, and the template provides a help example for a command <code>myCommand</code> as a syntax reminder. After each command declaration, the first line is the command syntax description, and the other lines are optional usage examples. Let's replace this help example with our own help information for our basic <code>!time</code> command:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
[time]
<nowiki>!</nowiki>time - This command just prints current time
|}

== Writing plugin code ==

The new-command plugin template that we used to initialize our plugin already defines a new command named <code>myCommand</code>, so all we have to do is to edit our plugin file ( <code>timeplugin.py</code> ) and replace this command by our own <code>time</code> command:

First, let's modify the code which sets up the new SPADS command handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addSpadsCommandHandler-handlers-replace-0 addSpadsCommandHandler]. This call is located in the plugin constructor. We edit it so that it becomes:
<syntaxhighlight lang="python">
[...]
# We declare our new command and the associated handler
spads.addSpadsCommandHandler({'time': hSpadsTime})
[...]
</syntaxhighlight>
We must modify the same way the code which removes this SPADS handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#removeSpadsCommandHandler-commands removeSpadsCommandHandler] in the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback:
<syntaxhighlight lang="python">
[...]
# We remove our new command handler
spads.removeSpadsCommandHandler(['time'])
[...]
</syntaxhighlight>
Finally, we must replace the handler example <code>hMyCommand</code> by our own handler <code>hSpadsTime</code>. In order to answer to the user issuing the command, we can use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#answer-message answer], which will send an answer message to the user in the same way he sent the command (private message, battle lobby...).

Here is an implementation example for this basic command:
<syntaxhighlight lang="python">
# This is the handler for our new command
def hSpadsTime(source,user,params,checkOnly):

# checkOnly is true if this is just a check for callVote command, not a real command execution
if checkOnly :

# time is a basic command, we have nothing to check in case of callvote
return 1

# We get current time using "now" function of datetime class from datetime module
current_time = datetime.datetime.now()
current_time_string = current_time.strftime("%H:%M:%S")

# We call the API function "answer" to send back the response to the user who called the command
# using same canal as he used (private message, battle lobby, in game message...)
spads.answer("Current local time: %s" % current_time_string)
</syntaxhighlight>

As we are retrieving current time in our plugin code, we must not forget to import the <code>datetime</code> Python module at the start of our plugin:
<syntaxhighlight lang="python">
# Import the datetime module so we can get current time for our !time command
import datetime
</syntaxhighlight>
Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/timeplugin.py this fully functional TimePlugin] plugin, and its associated [http://planetspads.free.fr/spads/plugins/tutorials/TimePlugin.conf configuration file], [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginCmd.conf command rights configuration file] and [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginHelp.dat command help file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module and the plugin help file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the 2 configuration files in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: <code>!plugin TimePlugin load</code>. And finally, we can try to say !time in a private message to SPADS or in the battle lobby, and SPADS should answer giving current local time. Our <code>!time</code> command help should also appear in <code>!help</code> and <code>!help time</code> outputs.

[[Category:SPADS]]

SPADS plugin development (Python)

2021-01-28T14:22:39Z

Bibim: /* New-command plugin tutorial (TimePlugin) */

= Introduction =

SPADS is an autohost system coded in Perl, it supports both Perl and Python plugins. This tutorial deals with Python plugin development only (for Perl plugin development another tutorial is available [https://springrts.com/wiki/SPADS_plugin_development here]).

SPADS plugins are object-oriented modules. It is strongly recommended to already know Python basics before starting Python plugin development (a Python tutorial is available [https://docs.python.org/3/tutorial/ here]).

 
= Technical prerequisites =

Python (the Python interpreter and its libraries) must be installed on the system (versions 2.6+ or 3.2+ recommended). The type of installation (32-bit / 64-bit) must be consistent with the Perl version and the Spring engine used for SPADS.

Additionally, in order to allow communication between Perl code (SPADS core) and Python code (SPADS plugins), SPADS uses a Perl module named <code>Inline::Python</code> which must also be installed on the system. It is recommended to install the latest version for SPADS, refer to [https://springrts.com/wiki/SPADS_Inline::Python_installation_guide this guide] for installation.

 

= 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 [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] (the <code>.pm</code> files must be ignored for this tutorial, these are the Perl versions of the templates).

Our first plugin will be very basic, so we will use the simplest template: <code>mysimpleplugin.py</code>. Let's download [http://planetspads.free.fr/spads/plugins/templates/commented/mysimpleplugin.py 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 <code>HelloWorld</code>. We have to rename the downloaded template from <code>mysimpleplugin.py</code> to <code>helloworld.py</code>, and edit it to replace <code>MySimplePlugin</code> by <code>HelloWorld</code> 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 <code>spads.conf</code> configuration file and reload SPADS configuration).

We have to move our new plugin (<code>helloworld.py</code>) 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): <code>!plugin HelloWorld load</code>. SPADS should answer <code>Loaded plugin HelloWorld.</code>, 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-self-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 <code>onPrivateMsg</code> callback, which will answer <code>Hello World</code> to anyone saying <code>Hello</code> in a private message to SPADS:
<syntaxhighlight lang="python">
# This is the callback called each time SPADS receives a private message
# 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
def onPrivateMsg(self,userName,message):

# Here we "fix" strings received from Perl in case
# the Inline::Python module transmits them as byte strings
(userName,message)=spads.fix_string(userName,message)

# We check the message sent by the user is "Hello"
if message == 'Hello':

# We send our wonderful Hello World message
spads.sayPrivate(userName,'Hello World')

# We return 0 because we don't want to filter out private messages
# for other SPADS processing
return 0</syntaxhighlight>

All we have to do now is adding this callback declaration in our <code>helloworld.py</code> file located in SPADS plugins directory. We obtain [http://planetspads.free.fr/spads/plugins/tutorials/helloworld.py 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: <code>!plugin HelloWorld reload</code>. SPADS should answer <code>Reloaded plugin HelloWorld.</code>, which indicates the plugin has been reloaded successfully.

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

 
= Configurable plugin tutorial (ForbiddenWords) =

In this section we are going to write our first configurable SPADS plugin (a configurable plugin has its own configuration file, named after the plugin name but with <code>.conf</code> extension). This plugin will monitor all messages said by players in the battle lobby, and will kick players who use swear words.

== Specifying our configuration parameters ==

The first step of writing a configurable plugin is to choose how we will configure it. In our example, we will use 2 configuration parameters: <code>words</code> will contain the list of forbidden words, and <code>immuneLevel</code> will contain the minimum autohost access level to be immune regarding these forbidden words checks.

We choose to make <code>words</code> a global setting (unmodifiable, not impacted by preset change), and <code>immuneLevel</code> a preset setting (modifiable, can be impacted by preset change). The <code>words</code> global setting will have no restriction (can be empty, can contain any character...), whereas the <code>immuneLevel</code> preset setting will only be allowed to be an integer or integer range.

== Preparing the template ==

Once we have a clear view of our configuration settings, we can start adapting the template for our needs. Since we are making a configurable plugin, this time we will download [http://planetspads.free.fr/spads/plugins/templates/commented/myconfigurableplugin.py the configurable plugin template] and its associated [http://planetspads.free.fr/spads/plugins/templates/commented/MyConfigurablePlugin.conf configuration file example].

First, let's take a look at the configuration file example. This is a just a basic configuration file containing one global setting example and one preset setting example. Let's modify this file to match the configuration we chose as follows (don't forget to rename the file from <code>MyConfigurablePlugin.conf</code> to <code>ForbiddenWords.conf</code> also):
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# This is our global setting (can't be changed without reloading the configuration)
words:ass;asshole;bastard;bitch;cunt;fuck;motherfucker;shit;whore

# We must define our preset setting in the default preset at least
[default]

# This is our preset setting, which can be changed with "!plugin ... set ..."
# or by loading a preset.
# "100" is the default value, and any integer between 0 and 140 is allowed
immuneLevel:100|0-140
|}
Then we must prepare the plugin template itself, by renaming it from <code>myconfigurableplugin.py</code> to <code>forbiddenwords.py</code> and editing it to replace <code>MyConfigurablePlugin</code> by <code>ForbiddenWords</code> in the source code. We must also adapt the template so that it uses the configuration settings we chose. This is done by modifying the <code>globalPluginParams</code> and <code>presetPluginParam</code> declarations as follows:
<syntaxhighlight lang="python">
# We define one global setting "words" and one preset setting "immuneLevel".
# "words" has no type associated (no restriction on allowed values)
# "immuneLevel" must be an integer or an integer range
# (check %paramTypes hash in SpadsConf.pm for a complete list of allowed
# setting types)
globalPluginParams = { 'words': [] }
presetPluginParams = { 'immuneLevel': ['integer','integerRange'] }
</syntaxhighlight>

== Writing plugin code ==

We want our plugin to react to messages said in the battle lobby. There is no dedicated callback for this event in [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html SPADS plugin API documentation], so we have to set up our own handler on the [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#SAIDBATTLE:server SAIDBATTLE lobby command]. To do so we have to call the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addLobbyCommandHandler-handlers-priority-caller addLobbyCommandHandler]. We will call this function at the end of our plugin constructor as follows, so that it will be set up directly when the plugin is loaded:
<syntaxhighlight lang="python">
[...]

# We set up a lobby command handler on SAIDBATTLE
spads.addLobbyCommandHandler({'SAIDBATTLE': hLobbySaidBattle})
</syntaxhighlight>
However, if SPADS is disconnected from the lobby due to network problems for example, all lobby handlers are automatically removed. So we must re-add them each time we connect to lobby server. This can be done using the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onLobbyConnected-self-lobbyInterface onLobbyConnected] event-based callback as follows:
<syntaxhighlight lang="python">
# This callback is called each time we (re)connect to the lobby server
def onLobbyConnected(self,lobbyInterface):

# When we are disconnected from the lobby server, all lobby command
# handlers are automatically removed, so we (re)set up our command
# handler here.
spads.addLobbyCommandHandler({'SAIDBATTLE': hLobbySaidBattle})
</syntaxhighlight>
Also, it is a good practice to remove any handler we have added when the plugin is unloaded. To do so we must implement the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback as follows:
<syntaxhighlight lang="python">
# This callback is called when the plugin is unloaded
def onUnload(self,reason):

# We remove our lobby command handler when the plugin is unloaded
spads.removeLobbyCommandHandler(['SAIDBATTLE'])
</syntaxhighlight>
Finally, we have to implement our <code>SAIDBATTLE</code> handler <code>hLobbySaidBattle</code>. In this handler we need to perform following operations:
* skip processing if the user is the autohost itself: we need to access SPADS configuration to compare the user name with the [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:lobbyLogin lobbyLogin] setting value. So we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getSpadsConf getSpadsConf].
* perform processing according to our configuration (<code>words</code> and <code>immuneLevel</code> settings): we need to access our plugin configuration, so we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getPluginConf-pluginName-caller getPluginConf].
* retrieve the autohost access level of the user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getUserAccessLevel-user getUserAccessLevel]
* send a message to the battle lobby when we kick someone: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#sayBattle-message sayBattle].
* send a [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#KICKFROMBATTLE:client KICKFROMBATTLE] lobby command to kick a user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#queueLobbyCommand-lobbyCommand queueLobbyCommand].

Here is a commented implementation example of this <code>hLobbySaidBattle</code> handler, which will kick any non-privileged user saying a forbidden word in the battle lobby:
<syntaxhighlight lang="python">
# This is the handler we set up on SAIDBATTLE lobby command.
# It is called each time a player says something in the battle lobby.
# command is the lobby command name (SAIDBATTLE)
# user is the name of the user who said something in the battle lobby
# message is the message said in the battle lobby
def hLobbySaidBattle(command,user,message):

# First we "fix" strings received from Perl in case
# the Inline::Python module transmits them as byte strings
(user,message)=spads.fix_string(user,message)

# Here we check it's not a message from SPADS (so we don't kick ourself)
spadsConf = spads.getSpadsConf()
if user == spadsConf['lobbyLogin']:
return

# Then we check the user isn't a privileged user
# (autohost access level >= immuneLevel)
pluginConf = spads.getPluginConf()
if int(spads.getUserAccessLevel(user)) >= int(pluginConf['immuneLevel']):
return

# We put the forbidden words in a list
forbiddenWords = pluginConf['words'].split(';')

# We test each forbidden word
for forbiddenWord in forbiddenWords:

# If the message contains the forbidden word (case insensitive)
if re.search(r'\b' + re.escape(forbiddenWord) + r'\b',message,re.IGNORECASE):

# Then we kick the user from the battle lobby
spads.sayBattle("Kicking %s from battle (watch your language!)" % user)
spads.queueLobbyCommand(["KICKFROMBATTLE",user])

# We quit the foreach loop (no need to test other forbidden word)
break
</syntaxhighlight>

As we are using regular expressions in our plugin code, we must not forget to import the <code>re</code> Python module at the start of our plugin:
<syntaxhighlight lang="python">
# Import the regular expression module to check for forbidden words
import re
</syntaxhighlight>
Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/forbiddenwords.py this fully functional ForbiddenWords] plugin and [http://planetspads.free.fr/spads/plugins/tutorials/ForbiddenWords.conf its associated configuration file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the associated configuration file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: <code>!plugin ForbiddenWords load</code>. And finally, as an unprivileged user we can try to say some forbidden words in the battle lobby and we should get kicked by the plugin.

 

'''/!\ WORK IN PROGRESS /!\'''

= New-command plugin tutorial (TimePlugin) =

In this section we are going to write a plugin which implements a new command for SPADS. Such plugins are configurable plugins like the one we wrote just before, with 2 additional files to configure the new commands. This plugin will give current time when someone types <code>!time</code>.

== Preparing the template ==

This time we need to download 4 files to prepare our plugin: [http://planetspads.free.fr/spads/plugins/templates/commented/mynewcommandplugin.py the new-command plugin template], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPlugin.conf the associated configuration file example], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginHelp.dat the help file example] and [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginCmd.conf the commands rights configuration file example].

As usual, we rename these files to match our plugin name: <code>MyNewCommandPlugin</code> --> <code>TimePlugin</code>. Then we edit the plugin template <code>timeplugin.py</code> and replace <code>MyNewCommandPlugin</code> by <code>TimePlugin</code> in the source code, and we do the same for the plugin configuration template <code>TimePlugin.conf</code>, so that the <code>commandsFile</code> and <code>helpFile</code> settings are consistent with the files we just renamed.

Then we can edit our command rights requirements configuration file: <code>TimePluginCmd.conf</code>. This file uses the same syntax as the standard SPADS <code>commands.conf</code> file. The template provides a default command <code>myCommand</code> with no requirement. We will just rename this command to <code>time</code>:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# Anyone can call our command from anywhere
[time]
::|0:
|}
Now we need to write the help information for our new command. This is done in the file <code>TimePluginHelp.dat</code>. This file uses the same syntax as the standard SPADS <code>help.dat</code> file, and the template provides a help example for a command <code>myCommand</code> as a syntax reminder. After each command declaration, the first line is the command syntax description, and the other lines are optional usage examples. Let's replace this help example with our own help information for our basic <code>!time</code> command:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
[time]
<nowiki>!</nowiki>time - This command just prints current time
|}

== Writing plugin code ==

The new-command plugin template that we used to initialize our plugin already defines a new command named <code>myCommand</code>, so all we have to do is to edit our plugin file ( <code>timeplugin.py</code> ) and replace this command by our own <code>time</code> command:

First, let's modify the code which sets up the new SPADS command handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addSpadsCommandHandler-handlers-replace-0 addSpadsCommandHandler]. This call is located in the plugin constructor. We edit it so that it becomes:
<syntaxhighlight lang="python">
[...]
# We declare our new command and the associated handler
spads.addSpadsCommandHandler({'time': hSpadsTime})
[...]
</syntaxhighlight>
We must modify the same way the code which removes this SPADS handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#removeSpadsCommandHandler-commands removeSpadsCommandHandler] in the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback:
<syntaxhighlight lang="python">
[...]
# We remove our new command handler
spads.removeSpadsCommandHandler(['time'])
[...]
</syntaxhighlight>
Finally, we must replace the handler example <code>hMyCommand</code> by our own handler <code>hSpadsTime</code>. In order to answer to the user issuing the command, we can use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#answer-message answer], which will send an answer message to the user in the same way he sent the command (private message, battle lobby...).

Here is an implementation example for this basic command:
<syntaxhighlight lang="python">
# This is the handler for our new command
def hSpadsTime(source,user,params,checkOnly):

# checkOnly is true if this is just a check for callVote command, not a real command execution
if checkOnly :

# time is a basic command, we have nothing to check in case of callvote
return 1

# We get current time using "now" function of datetime class from datetime module
current_time = datetime.datetime.now()
current_time_string = current_time.strftime("%H:%M:%S")

# We call the API function "answer" to send back the response to the user who called the command
# using same canal as he used (private message, battle lobby, in game message...)
spads.answer("Current local time: %s" % current_time_string)
</syntaxhighlight>

Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/timeplugin.py this fully functional TimePlugin] plugin, and its associated [http://planetspads.free.fr/spads/plugins/tutorials/TimePlugin.conf configuration file], [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginCmd.conf command rights configuration file] and [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginHelp.dat command help file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module and the plugin help file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the 2 configuration files in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: <code>!plugin TimePlugin load</code>. And finally, we can try to say !time in a private message to SPADS or in the battle lobby, and SPADS should answer giving current local time. Our <code>!time</code> command help should also appear in <code>!help</code> and <code>!help time</code> outputs.

[[Category:SPADS]]

SPADS plugin development (Python)

2021-01-28T13:24:02Z

Bibim: /* Writing plugin code */

= Introduction =

SPADS is an autohost system coded in Perl, it supports both Perl and Python plugins. This tutorial deals with Python plugin development only (for Perl plugin development another tutorial is available [https://springrts.com/wiki/SPADS_plugin_development here]).

SPADS plugins are object-oriented modules. It is strongly recommended to already know Python basics before starting Python plugin development (a Python tutorial is available [https://docs.python.org/3/tutorial/ here]).

 
= Technical prerequisites =

Python (the Python interpreter and its libraries) must be installed on the system (versions 2.6+ or 3.2+ recommended). The type of installation (32-bit / 64-bit) must be consistent with the Perl version and the Spring engine used for SPADS.

Additionally, in order to allow communication between Perl code (SPADS core) and Python code (SPADS plugins), SPADS uses a Perl module named <code>Inline::Python</code> which must also be installed on the system. It is recommended to install the latest version for SPADS, refer to [https://springrts.com/wiki/SPADS_Inline::Python_installation_guide this guide] for installation.

 

= 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 [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] (the <code>.pm</code> files must be ignored for this tutorial, these are the Perl versions of the templates).

Our first plugin will be very basic, so we will use the simplest template: <code>mysimpleplugin.py</code>. Let's download [http://planetspads.free.fr/spads/plugins/templates/commented/mysimpleplugin.py 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 <code>HelloWorld</code>. We have to rename the downloaded template from <code>mysimpleplugin.py</code> to <code>helloworld.py</code>, and edit it to replace <code>MySimplePlugin</code> by <code>HelloWorld</code> 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 <code>spads.conf</code> configuration file and reload SPADS configuration).

We have to move our new plugin (<code>helloworld.py</code>) 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): <code>!plugin HelloWorld load</code>. SPADS should answer <code>Loaded plugin HelloWorld.</code>, 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-self-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 <code>onPrivateMsg</code> callback, which will answer <code>Hello World</code> to anyone saying <code>Hello</code> in a private message to SPADS:
<syntaxhighlight lang="python">
# This is the callback called each time SPADS receives a private message
# 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
def onPrivateMsg(self,userName,message):

# Here we "fix" strings received from Perl in case
# the Inline::Python module transmits them as byte strings
(userName,message)=spads.fix_string(userName,message)

# We check the message sent by the user is "Hello"
if message == 'Hello':

# We send our wonderful Hello World message
spads.sayPrivate(userName,'Hello World')

# We return 0 because we don't want to filter out private messages
# for other SPADS processing
return 0</syntaxhighlight>

All we have to do now is adding this callback declaration in our <code>helloworld.py</code> file located in SPADS plugins directory. We obtain [http://planetspads.free.fr/spads/plugins/tutorials/helloworld.py 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: <code>!plugin HelloWorld reload</code>. SPADS should answer <code>Reloaded plugin HelloWorld.</code>, which indicates the plugin has been reloaded successfully.

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

 
= Configurable plugin tutorial (ForbiddenWords) =

In this section we are going to write our first configurable SPADS plugin (a configurable plugin has its own configuration file, named after the plugin name but with <code>.conf</code> extension). This plugin will monitor all messages said by players in the battle lobby, and will kick players who use swear words.

== Specifying our configuration parameters ==

The first step of writing a configurable plugin is to choose how we will configure it. In our example, we will use 2 configuration parameters: <code>words</code> will contain the list of forbidden words, and <code>immuneLevel</code> will contain the minimum autohost access level to be immune regarding these forbidden words checks.

We choose to make <code>words</code> a global setting (unmodifiable, not impacted by preset change), and <code>immuneLevel</code> a preset setting (modifiable, can be impacted by preset change). The <code>words</code> global setting will have no restriction (can be empty, can contain any character...), whereas the <code>immuneLevel</code> preset setting will only be allowed to be an integer or integer range.

== Preparing the template ==

Once we have a clear view of our configuration settings, we can start adapting the template for our needs. Since we are making a configurable plugin, this time we will download [http://planetspads.free.fr/spads/plugins/templates/commented/myconfigurableplugin.py the configurable plugin template] and its associated [http://planetspads.free.fr/spads/plugins/templates/commented/MyConfigurablePlugin.conf configuration file example].

First, let's take a look at the configuration file example. This is a just a basic configuration file containing one global setting example and one preset setting example. Let's modify this file to match the configuration we chose as follows (don't forget to rename the file from <code>MyConfigurablePlugin.conf</code> to <code>ForbiddenWords.conf</code> also):
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# This is our global setting (can't be changed without reloading the configuration)
words:ass;asshole;bastard;bitch;cunt;fuck;motherfucker;shit;whore

# We must define our preset setting in the default preset at least
[default]

# This is our preset setting, which can be changed with "!plugin ... set ..."
# or by loading a preset.
# "100" is the default value, and any integer between 0 and 140 is allowed
immuneLevel:100|0-140
|}
Then we must prepare the plugin template itself, by renaming it from <code>myconfigurableplugin.py</code> to <code>forbiddenwords.py</code> and editing it to replace <code>MyConfigurablePlugin</code> by <code>ForbiddenWords</code> in the source code. We must also adapt the template so that it uses the configuration settings we chose. This is done by modifying the <code>globalPluginParams</code> and <code>presetPluginParam</code> declarations as follows:
<syntaxhighlight lang="python">
# We define one global setting "words" and one preset setting "immuneLevel".
# "words" has no type associated (no restriction on allowed values)
# "immuneLevel" must be an integer or an integer range
# (check %paramTypes hash in SpadsConf.pm for a complete list of allowed
# setting types)
globalPluginParams = { 'words': [] }
presetPluginParams = { 'immuneLevel': ['integer','integerRange'] }
</syntaxhighlight>

== Writing plugin code ==

We want our plugin to react to messages said in the battle lobby. There is no dedicated callback for this event in [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html SPADS plugin API documentation], so we have to set up our own handler on the [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#SAIDBATTLE:server SAIDBATTLE lobby command]. To do so we have to call the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addLobbyCommandHandler-handlers-priority-caller addLobbyCommandHandler]. We will call this function at the end of our plugin constructor as follows, so that it will be set up directly when the plugin is loaded:
<syntaxhighlight lang="python">
[...]

# We set up a lobby command handler on SAIDBATTLE
spads.addLobbyCommandHandler({'SAIDBATTLE': hLobbySaidBattle})
</syntaxhighlight>
However, if SPADS is disconnected from the lobby due to network problems for example, all lobby handlers are automatically removed. So we must re-add them each time we connect to lobby server. This can be done using the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onLobbyConnected-self-lobbyInterface onLobbyConnected] event-based callback as follows:
<syntaxhighlight lang="python">
# This callback is called each time we (re)connect to the lobby server
def onLobbyConnected(self,lobbyInterface):

# When we are disconnected from the lobby server, all lobby command
# handlers are automatically removed, so we (re)set up our command
# handler here.
spads.addLobbyCommandHandler({'SAIDBATTLE': hLobbySaidBattle})
</syntaxhighlight>
Also, it is a good practice to remove any handler we have added when the plugin is unloaded. To do so we must implement the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback as follows:
<syntaxhighlight lang="python">
# This callback is called when the plugin is unloaded
def onUnload(self,reason):

# We remove our lobby command handler when the plugin is unloaded
spads.removeLobbyCommandHandler(['SAIDBATTLE'])
</syntaxhighlight>
Finally, we have to implement our <code>SAIDBATTLE</code> handler <code>hLobbySaidBattle</code>. In this handler we need to perform following operations:
* skip processing if the user is the autohost itself: we need to access SPADS configuration to compare the user name with the [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:lobbyLogin lobbyLogin] setting value. So we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getSpadsConf getSpadsConf].
* perform processing according to our configuration (<code>words</code> and <code>immuneLevel</code> settings): we need to access our plugin configuration, so we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getPluginConf-pluginName-caller getPluginConf].
* retrieve the autohost access level of the user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getUserAccessLevel-user getUserAccessLevel]
* send a message to the battle lobby when we kick someone: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#sayBattle-message sayBattle].
* send a [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#KICKFROMBATTLE:client KICKFROMBATTLE] lobby command to kick a user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#queueLobbyCommand-lobbyCommand queueLobbyCommand].

Here is a commented implementation example of this <code>hLobbySaidBattle</code> handler, which will kick any non-privileged user saying a forbidden word in the battle lobby:
<syntaxhighlight lang="python">
# This is the handler we set up on SAIDBATTLE lobby command.
# It is called each time a player says something in the battle lobby.
# command is the lobby command name (SAIDBATTLE)
# user is the name of the user who said something in the battle lobby
# message is the message said in the battle lobby
def hLobbySaidBattle(command,user,message):

# First we "fix" strings received from Perl in case
# the Inline::Python module transmits them as byte strings
(user,message)=spads.fix_string(user,message)

# Here we check it's not a message from SPADS (so we don't kick ourself)
spadsConf = spads.getSpadsConf()
if user == spadsConf['lobbyLogin']:
return

# Then we check the user isn't a privileged user
# (autohost access level >= immuneLevel)
pluginConf = spads.getPluginConf()
if int(spads.getUserAccessLevel(user)) >= int(pluginConf['immuneLevel']):
return

# We put the forbidden words in a list
forbiddenWords = pluginConf['words'].split(';')

# We test each forbidden word
for forbiddenWord in forbiddenWords:

# If the message contains the forbidden word (case insensitive)
if re.search(r'\b' + re.escape(forbiddenWord) + r'\b',message,re.IGNORECASE):

# Then we kick the user from the battle lobby
spads.sayBattle("Kicking %s from battle (watch your language!)" % user)
spads.queueLobbyCommand(["KICKFROMBATTLE",user])

# We quit the foreach loop (no need to test other forbidden word)
break
</syntaxhighlight>

As we are using regular expressions in our plugin code, we must not forget to import the <code>re</code> Python module at the start of our plugin:
<syntaxhighlight lang="python">
# Import the regular expression module to check for forbidden words
import re
</syntaxhighlight>
Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/forbiddenwords.py this fully functional ForbiddenWords] plugin and [http://planetspads.free.fr/spads/plugins/tutorials/ForbiddenWords.conf its associated configuration file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the associated configuration file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: <code>!plugin ForbiddenWords load</code>. And finally, as an unprivileged user we can try to say some forbidden words in the battle lobby and we should get kicked by the plugin.

 

'''/!\ WORK IN PROGRESS /!\'''

= New-command plugin tutorial (TimePlugin) =

In this section we are going to write a plugin which implements a new command for SPADS. Such plugins are configurable plugins like the one we wrote just before, with 2 additional files to configure the new commands. This plugin will give current time when someone types <code>!time</code>.

== Preparing the template ==

This time we need to download 4 files to prepare our plugin: [http://planetspads.free.fr/spads/plugins/templates/commented/mynewcommandplugin.py the new-command plugin template], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPlugin.conf the associated configuration file example], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginHelp.dat the help file example] and [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginCmd.conf the commands rights configuration file example].

As usual, we rename these files to match our plugin name: <code>MyNewCommandPlugin</code> --> <code>TimePlugin</code>. Then we edit the plugin template <code>timeplugin.py</code> and replace <code>MyNewCommandPlugin</code> by <code>TimePlugin</code> in the source code, and we do the same for the plugin configuration template <code>TimePlugin.conf</code>, so that the <code>commandsFile</code> and <code>helpFile</code> settings are consistent with the files we just renamed.

Then we can edit our command rights requirements configuration file: <code>TimePluginCmd.conf</code>. This file uses the same syntax as the standard SPADS <code>commands.conf</code> file. The template provides a default command <code>myCommand</code> with no requirement. We will just rename this command to <code>time</code>:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# Anyone can call our command from anywhere
[time]
::|0:
|}
Now we need to write the help information for our new command. This is done in the file <code>TimePluginHelp.dat</code>. This file uses the same syntax as the standard SPADS <code>help.dat</code> file, and the template provides a help example for a command <code>myCommand</code> as a syntax reminder. After each command declaration, the first line is the command syntax description, and the other lines are optional usage examples. Let's replace this help example with our own help information for our basic <code>!time</code> command:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
[time]
<nowiki>!</nowiki>time - This command just prints current time
|}

== Writing plugin code ==

The new-command plugin template that we used to initialize our plugin already defines a new command named <code>myCommand</code>, so all we have to do is to edit our plugin file ( <code>timeplugin.py</code> ) and replace this command by our own <code>time</code> command:

First, let's modify the code which sets up the new SPADS command handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addSpadsCommandHandler-handlers-replace-0 addSpadsCommandHandler]. This call is located in the plugin constructor. We edit it so that it becomes:
<syntaxhighlight lang="python">
[...]
# We declare our new command and the associated handler
spads.addSpadsCommandHandler({'time': hSpadsTime})
[...]
</syntaxhighlight>
We must modify the same way the code which removes this SPADS handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#removeSpadsCommandHandler-commands removeSpadsCommandHandler] in the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback:
<syntaxhighlight lang="python">
[...]
# We remove our new command handler
spads.removeSpadsCommandHandler(['time'])
[...]
</syntaxhighlight>
Finally, we must replace the handler example <code>hMyCommand</code> by our own handler <code>hSpadsTime</code>. In order to answer to the user issuing the command, we can use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#answer-message answer], which will send an answer message to the user in the same way he sent the command (private message, battle lobby...).

Here is an implementation example for this basic command:
<syntaxhighlight lang="python">
# This is the handler for our new command
def hSpadsTime(source,user,params,checkOnly):

# time is a basic command, we have nothing to check in case of callvote
return 1 if($checkOnly);

my @time = localtime();
@time = map(sprintf("%02d",$_),@time);

answer("Current local time: $time[2]:$time[1]:$time[0]");
}
</syntaxhighlight>

Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/timeplugin.py this fully functional TimePlugin] plugin, and its associated [http://planetspads.free.fr/spads/plugins/tutorials/TimePlugin.conf configuration file], [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginCmd.conf command rights configuration file] and [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginHelp.dat command help file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module and the plugin help file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the 2 configuration files in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: <code>!plugin TimePlugin load</code>. And finally, we can try to say !time in a private message to SPADS or in the battle lobby, and SPADS should answer giving current local time. Our <code>!time</code> command help should also appear in <code>!help</code> and <code>!help time</code> outputs.

[[Category:SPADS]]

SPADS plugin development (Python)

2021-01-28T13:20:50Z

Bibim: /* Preparing the template */

= Introduction =

SPADS is an autohost system coded in Perl, it supports both Perl and Python plugins. This tutorial deals with Python plugin development only (for Perl plugin development another tutorial is available [https://springrts.com/wiki/SPADS_plugin_development here]).

SPADS plugins are object-oriented modules. It is strongly recommended to already know Python basics before starting Python plugin development (a Python tutorial is available [https://docs.python.org/3/tutorial/ here]).

 
= Technical prerequisites =

Python (the Python interpreter and its libraries) must be installed on the system (versions 2.6+ or 3.2+ recommended). The type of installation (32-bit / 64-bit) must be consistent with the Perl version and the Spring engine used for SPADS.

Additionally, in order to allow communication between Perl code (SPADS core) and Python code (SPADS plugins), SPADS uses a Perl module named <code>Inline::Python</code> which must also be installed on the system. It is recommended to install the latest version for SPADS, refer to [https://springrts.com/wiki/SPADS_Inline::Python_installation_guide this guide] for installation.

 

= 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 [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] (the <code>.pm</code> files must be ignored for this tutorial, these are the Perl versions of the templates).

Our first plugin will be very basic, so we will use the simplest template: <code>mysimpleplugin.py</code>. Let's download [http://planetspads.free.fr/spads/plugins/templates/commented/mysimpleplugin.py 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 <code>HelloWorld</code>. We have to rename the downloaded template from <code>mysimpleplugin.py</code> to <code>helloworld.py</code>, and edit it to replace <code>MySimplePlugin</code> by <code>HelloWorld</code> 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 <code>spads.conf</code> configuration file and reload SPADS configuration).

We have to move our new plugin (<code>helloworld.py</code>) 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): <code>!plugin HelloWorld load</code>. SPADS should answer <code>Loaded plugin HelloWorld.</code>, 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-self-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 <code>onPrivateMsg</code> callback, which will answer <code>Hello World</code> to anyone saying <code>Hello</code> in a private message to SPADS:
<syntaxhighlight lang="python">
# This is the callback called each time SPADS receives a private message
# 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
def onPrivateMsg(self,userName,message):

# Here we "fix" strings received from Perl in case
# the Inline::Python module transmits them as byte strings
(userName,message)=spads.fix_string(userName,message)

# We check the message sent by the user is "Hello"
if message == 'Hello':

# We send our wonderful Hello World message
spads.sayPrivate(userName,'Hello World')

# We return 0 because we don't want to filter out private messages
# for other SPADS processing
return 0</syntaxhighlight>

All we have to do now is adding this callback declaration in our <code>helloworld.py</code> file located in SPADS plugins directory. We obtain [http://planetspads.free.fr/spads/plugins/tutorials/helloworld.py 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: <code>!plugin HelloWorld reload</code>. SPADS should answer <code>Reloaded plugin HelloWorld.</code>, which indicates the plugin has been reloaded successfully.

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

 
= Configurable plugin tutorial (ForbiddenWords) =

In this section we are going to write our first configurable SPADS plugin (a configurable plugin has its own configuration file, named after the plugin name but with <code>.conf</code> extension). This plugin will monitor all messages said by players in the battle lobby, and will kick players who use swear words.

== Specifying our configuration parameters ==

The first step of writing a configurable plugin is to choose how we will configure it. In our example, we will use 2 configuration parameters: <code>words</code> will contain the list of forbidden words, and <code>immuneLevel</code> will contain the minimum autohost access level to be immune regarding these forbidden words checks.

We choose to make <code>words</code> a global setting (unmodifiable, not impacted by preset change), and <code>immuneLevel</code> a preset setting (modifiable, can be impacted by preset change). The <code>words</code> global setting will have no restriction (can be empty, can contain any character...), whereas the <code>immuneLevel</code> preset setting will only be allowed to be an integer or integer range.

== Preparing the template ==

Once we have a clear view of our configuration settings, we can start adapting the template for our needs. Since we are making a configurable plugin, this time we will download [http://planetspads.free.fr/spads/plugins/templates/commented/myconfigurableplugin.py the configurable plugin template] and its associated [http://planetspads.free.fr/spads/plugins/templates/commented/MyConfigurablePlugin.conf configuration file example].

First, let's take a look at the configuration file example. This is a just a basic configuration file containing one global setting example and one preset setting example. Let's modify this file to match the configuration we chose as follows (don't forget to rename the file from <code>MyConfigurablePlugin.conf</code> to <code>ForbiddenWords.conf</code> also):
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# This is our global setting (can't be changed without reloading the configuration)
words:ass;asshole;bastard;bitch;cunt;fuck;motherfucker;shit;whore

# We must define our preset setting in the default preset at least
[default]

# This is our preset setting, which can be changed with "!plugin ... set ..."
# or by loading a preset.
# "100" is the default value, and any integer between 0 and 140 is allowed
immuneLevel:100|0-140
|}
Then we must prepare the plugin template itself, by renaming it from <code>myconfigurableplugin.py</code> to <code>forbiddenwords.py</code> and editing it to replace <code>MyConfigurablePlugin</code> by <code>ForbiddenWords</code> in the source code. We must also adapt the template so that it uses the configuration settings we chose. This is done by modifying the <code>globalPluginParams</code> and <code>presetPluginParam</code> declarations as follows:
<syntaxhighlight lang="python">
# We define one global setting "words" and one preset setting "immuneLevel".
# "words" has no type associated (no restriction on allowed values)
# "immuneLevel" must be an integer or an integer range
# (check %paramTypes hash in SpadsConf.pm for a complete list of allowed
# setting types)
globalPluginParams = { 'words': [] }
presetPluginParams = { 'immuneLevel': ['integer','integerRange'] }
</syntaxhighlight>

== Writing plugin code ==

We want our plugin to react to messages said in the battle lobby. There is no dedicated callback for this event in [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html SPADS plugin API documentation], so we have to set up our own handler on the [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#SAIDBATTLE:server SAIDBATTLE lobby command]. To do so we have to call the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addLobbyCommandHandler-handlers-priority-caller addLobbyCommandHandler]. We will call this function at the end of our plugin constructor as follows, so that it will be set up directly when the plugin is loaded:
<syntaxhighlight lang="python">
[...]

# We set up a lobby command handler on SAIDBATTLE
spads.addLobbyCommandHandler({'SAIDBATTLE': hLobbySaidBattle})
</syntaxhighlight>
However, if SPADS is disconnected from the lobby due to network problems for example, all lobby handlers are automatically removed. So we must re-add them each time we connect to lobby server. This can be done using the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onLobbyConnected-self-lobbyInterface onLobbyConnected] event-based callback as follows:
<syntaxhighlight lang="python">
# This callback is called each time we (re)connect to the lobby server
def onLobbyConnected(self,lobbyInterface):

# When we are disconnected from the lobby server, all lobby command
# handlers are automatically removed, so we (re)set up our command
# handler here.
spads.addLobbyCommandHandler({'SAIDBATTLE': hLobbySaidBattle})
</syntaxhighlight>
Also, it is a good practice to remove any handler we have added when the plugin is unloaded. To do so we must implement the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback as follows:
<syntaxhighlight lang="python">
# This callback is called when the plugin is unloaded
def onUnload(self,reason):

# We remove our lobby command handler when the plugin is unloaded
spads.removeLobbyCommandHandler(['SAIDBATTLE'])
</syntaxhighlight>
Finally, we have to implement our <code>SAIDBATTLE</code> handler <code>hLobbySaidBattle</code>. In this handler we need to perform following operations:
* skip processing if the user is the autohost itself: we need to access SPADS configuration to compare the user name with the [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:lobbyLogin lobbyLogin] setting value. So we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getSpadsConf getSpadsConf].
* perform processing according to our configuration (<code>words</code> and <code>immuneLevel</code> settings): we need to access our plugin configuration, so we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getPluginConf-pluginName-caller getPluginConf].
* retrieve the autohost access level of the user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getUserAccessLevel-user getUserAccessLevel]
* send a message to the battle lobby when we kick someone: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#sayBattle-message sayBattle].
* send a [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#KICKFROMBATTLE:client KICKFROMBATTLE] lobby command to kick a user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#queueLobbyCommand-lobbyCommand queueLobbyCommand].

Here is a commented implementation example of this <code>hLobbySaidBattle</code> handler, which will kick any non-privileged user saying a forbidden word in the battle lobby:
<syntaxhighlight lang="python">
# This is the handler we set up on SAIDBATTLE lobby command.
# It is called each time a player says something in the battle lobby.
# command is the lobby command name (SAIDBATTLE)
# user is the name of the user who said something in the battle lobby
# message is the message said in the battle lobby
def hLobbySaidBattle(command,user,message):

# First we "fix" strings received from Perl in case
# the Inline::Python module transmits them as byte strings
(user,message)=spads.fix_string(user,message)

# Here we check it's not a message from SPADS (so we don't kick ourself)
spadsConf = spads.getSpadsConf()
if user == spadsConf['lobbyLogin']:
return

# Then we check the user isn't a privileged user
# (autohost access level >= immuneLevel)
pluginConf = spads.getPluginConf()
if int(spads.getUserAccessLevel(user)) >= int(pluginConf['immuneLevel']):
return

# We put the forbidden words in a list
forbiddenWords = pluginConf['words'].split(';')

# We test each forbidden word
for forbiddenWord in forbiddenWords:

# If the message contains the forbidden word (case insensitive)
if re.search(r'\b' + re.escape(forbiddenWord) + r'\b',message,re.IGNORECASE):

# Then we kick the user from the battle lobby
spads.sayBattle("Kicking %s from battle (watch your language!)" % user)
spads.queueLobbyCommand(["KICKFROMBATTLE",user])

# We quit the foreach loop (no need to test other forbidden word)
break
</syntaxhighlight>

As we are using regular expressions in our plugin code, we must not forget to import the <code>re</code> Python module at the start of our plugin:
<syntaxhighlight lang="python">
# Import the regular expression module to check for forbidden words
import re
</syntaxhighlight>
Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/forbiddenwords.py this fully functional ForbiddenWords] plugin and [http://planetspads.free.fr/spads/plugins/tutorials/ForbiddenWords.conf its associated configuration file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the associated configuration file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: <code>!plugin ForbiddenWords load</code>. And finally, as an unprivileged user we can try to say some forbidden words in the battle lobby and we should get kicked by the plugin.

 

'''/!\ WORK IN PROGRESS /!\'''

= New-command plugin tutorial (TimePlugin) =

In this section we are going to write a plugin which implements a new command for SPADS. Such plugins are configurable plugins like the one we wrote just before, with 2 additional files to configure the new commands. This plugin will give current time when someone types <code>!time</code>.

== Preparing the template ==

This time we need to download 4 files to prepare our plugin: [http://planetspads.free.fr/spads/plugins/templates/commented/mynewcommandplugin.py the new-command plugin template], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPlugin.conf the associated configuration file example], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginHelp.dat the help file example] and [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginCmd.conf the commands rights configuration file example].

As usual, we rename these files to match our plugin name: <code>MyNewCommandPlugin</code> --> <code>TimePlugin</code>. Then we edit the plugin template <code>timeplugin.py</code> and replace <code>MyNewCommandPlugin</code> by <code>TimePlugin</code> in the source code, and we do the same for the plugin configuration template <code>TimePlugin.conf</code>, so that the <code>commandsFile</code> and <code>helpFile</code> settings are consistent with the files we just renamed.

Then we can edit our command rights requirements configuration file: <code>TimePluginCmd.conf</code>. This file uses the same syntax as the standard SPADS <code>commands.conf</code> file. The template provides a default command <code>myCommand</code> with no requirement. We will just rename this command to <code>time</code>:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# Anyone can call our command from anywhere
[time]
::|0:
|}
Now we need to write the help information for our new command. This is done in the file <code>TimePluginHelp.dat</code>. This file uses the same syntax as the standard SPADS <code>help.dat</code> file, and the template provides a help example for a command <code>myCommand</code> as a syntax reminder. After each command declaration, the first line is the command syntax description, and the other lines are optional usage examples. Let's replace this help example with our own help information for our basic <code>!time</code> command:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
[time]
<nowiki>!</nowiki>time - This command just prints current time
|}

== Writing plugin code ==

The new-command plugin template that we used to initialize our plugin already defines a new command named <code>myCommand</code>, so all we have to do is to edit our plugin file ( <code>timeplugin.py</code> ) and replace this command by our own <code>time</code> command:

First, let's modify the code which sets up the new SPADS command handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addSpadsCommandHandler-handlers-replace-0 addSpadsCommandHandler]. This call is located in the plugin constructor. We edit it so that it becomes:
<syntaxhighlight lang="python">
[...]
# We declare our new command and the associated handler
addSpadsCommandHandler({time => \&hSpadsTime});
[...]
</syntaxhighlight>
We must modify the same way the code which removes this SPADS handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#removeSpadsCommandHandler-commands removeSpadsCommandHandler] in the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback:
<syntaxhighlight lang="python">
[...]
# We remove our new command handler
removeSpadsCommandHandler(['time']);
[...]
</syntaxhighlight>
Finally, we must replace the handler example <code>hMyCommand</code> by our own handler <code>hSpadsTime</code>. In order to answer to the user issuing the command, we can use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#answer-message answer], which will send an answer message to the user in the same way he sent the command (private message, battle lobby...).

Here is an implementation example for this basic command:
<syntaxhighlight lang="python">
# This is the handler for our new command
sub hSpadsTime {
my ($source,$user,$p_params,$checkOnly)=@_;

# time is a basic command, we have nothing to check in case of callvote
return 1 if($checkOnly);

my @time = localtime();
@time = map(sprintf("%02d",$_),@time);

answer("Current local time: $time[2]:$time[1]:$time[0]");
}
</syntaxhighlight>

Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/timeplugin.py this fully functional TimePlugin] plugin, and its associated [http://planetspads.free.fr/spads/plugins/tutorials/TimePlugin.conf configuration file], [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginCmd.conf command rights configuration file] and [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginHelp.dat command help file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module and the plugin help file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the 2 configuration files in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: <code>!plugin TimePlugin load</code>. And finally, we can try to say !time in a private message to SPADS or in the battle lobby, and SPADS should answer giving current local time. Our <code>!time</code> command help should also appear in <code>!help</code> and <code>!help time</code> outputs.

[[Category:SPADS]]

SPADS plugin development

2021-01-28T13:19:37Z

Bibim: /* Writing plugin code */

= Introduction =

SPADS is an autohost system coded in Perl, it supports both Perl and Python plugins. This tutorial deals with Perl plugin development only (for Python plugin development another tutorial is available [https://springrts.com/wiki/SPADS_plugin_development_(Python) here]).

SPADS plugins are object-oriented modules. It is strongly recommended to already know Perl basics before starting Perl plugin development (a brief introduction to Perl is available [https://perldoc.perl.org/perlintro here]).

 
= 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 [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] (the <code>.py</code> files must be ignored for this tutorial, these are the Python versions of the templates).

Our first plugin will be very basic, so we will use the simplest template: <code>MySimplePlugin.pm</code>. 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 <code>HelloWorld</code>. We have to rename the downloaded template from <code>MySimplePlugin.pm</code> to <code>HelloWorld.pm</code>, and edit it to replace <code>MySimplePlugin</code> by <code>HelloWorld</code> 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 <code>spads.conf</code> configuration file and reload SPADS configuration).

We have to move our new plugin (<code>HelloWorld.pm</code>) 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): <code>!plugin HelloWorld load</code>. SPADS should answer <code>Loaded plugin HelloWorld.</code>, 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-self-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 <code>onPrivateMsg</code> callback, which will answer <code>Hello World</code> to anyone saying <code>Hello</code> in a private message to SPADS:
<syntaxhighlight lang="perl">
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;

}</syntaxhighlight>

All we have to do now is adding this callback declaration in our <code>HelloWorld.pm</code> 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: <code>!plugin HelloWorld reload</code>. SPADS should answer <code>Reloaded plugin HelloWorld.</code>, which indicates the plugin has been reloaded successfully.

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

 
= Configurable plugin tutorial (ForbiddenWords) =

In this section we are going to write our first configurable SPADS plugin (a configurable plugin has its own configuration file, named after the plugin name but with <code>.conf</code> extension). This plugin will monitor all messages said by players in the battle lobby, and will kick players who use swear words.

== Specifying our configuration parameters ==

The first step of writing a configurable plugin is to choose how we will configure it. In our example, we will use 2 configuration parameters: <code>words</code> will contain the list of forbidden words, and <code>immuneLevel</code> will contain the minimum autohost access level to be immune regarding these forbidden words checks.

We choose to make <code>words</code> a global setting (unmodifiable, not impacted by preset change), and <code>immuneLevel</code> a preset setting (modifiable, can be impacted by preset change). The <code>words</code> global setting will have no restriction (can be empty, can contain any character...), whereas the <code>immuneLevel</code> preset setting will only be allowed to be an integer or integer range.

== Preparing the template ==

Once we have a clear view of our configuration settings, we can start adapting the template for our needs. Since we are making a configurable plugin, this time we will download [http://planetspads.free.fr/spads/plugins/templates/commented/MyConfigurablePlugin.pm the configurable plugin template] and its associated [http://planetspads.free.fr/spads/plugins/templates/commented/MyConfigurablePlugin.conf configuration file example].

First, let's take a look at the configuration file example. This is a just a basic configuration file containing one global setting example and one preset setting example. Let's modify this file to match the configuration we chose as follows (don't forget to rename the file from <code>MyConfigurablePlugin.conf</code> to <code>ForbiddenWords.conf</code> also):
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# This is our global setting (can't be changed without reloading the configuration)
words:ass;asshole;bastard;bitch;cunt;fuck;motherfucker;shit;whore

# We must define our preset setting in the default preset at least
[default]

# This is our preset setting, which can be changed with "!plugin ... set ..."
# or by loading a preset.
# "100" is the default value, and any integer between 0 and 140 is allowed
immuneLevel:100|0-140
|}
Then we must prepare the plugin template itself, by renaming it from <code>MyConfigurablePlugin.pm</code> to <code>ForbiddenWords.pm</code> and editing it to replace <code>MyConfigurablePlugin</code> by <code>ForbiddenWords</code> in the source code. We must also adapt the template so that it uses the configuration settings we chose. This is done by modifying the <code>%globalPluginParams</code> and <code>%presetPluginParam</code> declarations as follows:
<syntaxhighlight lang="perl">
# We define one global setting "words" and one preset setting "immuneLevel".
# "words" has no type associated (no restriction on allowed values)
# "immuneLevel" must be an integer or an integer range
# (check %paramTypes hash in SpadsConf.pm for a complete list of allowed
# setting types)
my %globalPluginParams = ( words => [] );
my %presetPluginParams = ( immuneLevel => ['integer','integerRange'] );
</syntaxhighlight>

== Writing plugin code ==

We want our plugin to react to messages said in the battle lobby. There is no dedicated callback for this event in [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html SPADS plugin API documentation], so we have to set up our own handler on the [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#SAIDBATTLE:server SAIDBATTLE lobby command]. To do so we have to call the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addLobbyCommandHandler-handlers-priority-caller addLobbyCommandHandler]. We will call this function at the end of our plugin constructor as follows, so that it will be set up directly when the plugin is loaded:
<syntaxhighlight lang="perl">
[...]

# We set up a lobby command handler on SAIDBATTLE
addLobbyCommandHandler({SAIDBATTLE => \&hLobbySaidBattle});

# We return the instantiated plugin
return $self;

}
</syntaxhighlight>
However, if SPADS is disconnected from the lobby due to network problems for example, all lobby handlers are automatically removed. So we must re-add them each time we connect to lobby server. This can be done using the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onLobbyConnected-self-lobbyInterface onLobbyConnected] event-based callback as follows:
<syntaxhighlight lang="perl">
# This callback is called each time we (re)connect to the lobby server
sub onLobbyConnected {

# When we are disconnected from the lobby server, all lobby command
# handlers are automatically removed, so we (re)set up our command
# handler here.
addLobbyCommandHandler({SAIDBATTLE => \&hLobbySaidBattle});

}
</syntaxhighlight>
Also, it is a good practice to remove any handler we have added when the plugin is unloaded. To do so we must implement the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback as follows:
<syntaxhighlight lang="perl">
# This callback is called when the plugin is unloaded
sub onUnload {

# We remove our lobby command handler when the plugin is unloaded
removeLobbyCommandHandler(['SAIDBATTLE']);

}
</syntaxhighlight>
Finally, we have to implement our <code>SAIDBATTLE</code> handler <code>hLobbySaidBattle</code>. In this handler we need to perform following operations:
* skip processing if the user is the autohost itself: we need to access SPADS configuration to compare the user name with the [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:lobbyLogin lobbyLogin] setting value. So we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getSpadsConf getSpadsConf].
* perform processing according to our configuration (<code>words</code> and <code>immuneLevel</code> settings): we need to access our plugin configuration, so we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getPluginConf-pluginName-caller getPluginConf].
* retrieve the autohost access level of the user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getUserAccessLevel-user getUserAccessLevel]
* send a message to the battle lobby when we kick someone: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#sayBattle-message sayBattle].
* send a [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#KICKFROMBATTLE:client KICKFROMBATTLE] lobby command to kick a user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#queueLobbyCommand-lobbyCommand queueLobbyCommand].

Here is a commented implementation example of this <code>hLobbySaidBattle</code> handler, which will kick any non-privileged user saying a forbidden word in the battle lobby:
<syntaxhighlight lang="perl">
# This is the handler we set up on SAIDBATTLE lobby command.
# It is called each time a player says something in the battle lobby.
sub hLobbySaidBattle {

# $command is the lobby command name (SAIDBATTLE)
# $user is the name of the user who said something in the battle lobby
# $message is the message said in the battle lobby
my ($command,$user,$message)=@_;

# First we check it's not a message from SPADS (so we don't kick ourself)
my $p_spadsConf=getSpadsConf();
return if($user eq $p_spadsConf->{lobbyLogin});

# Then we check the user isn't a privileged user
# (autohost access level >= immuneLevel)
my $p_conf=getPluginConf();
return if(getUserAccessLevel($user) >= $p_conf->{immuneLevel});

# We put the forbidden words in a array
my @forbiddenWords=split(/;/,$p_conf->{words});

# We test each forbidden word
foreach my $forbiddenWord (@forbiddenWords) {

# If the message contains the forbidden word (case insensitive)
if($message =~ /\b$forbiddenWord\b/i) {

# Then we kick the user from the battle lobby
sayBattle("Kicking $user from battle (watch your language!)");
queueLobbyCommand(["KICKFROMBATTLE",$user]);

# We quit the foreach loop (no need to test other forbidden word)
last;

}

}

}
</syntaxhighlight>
Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/ForbiddenWords.pm this fully functional ForbiddenWords] plugin and [http://planetspads.free.fr/spads/plugins/tutorials/ForbiddenWords.conf its associated configuration file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the associated configuration file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: <code>!plugin ForbiddenWords load</code>. And finally, as an unprivileged user we can try to say some forbidden words in the battle lobby and we should get kicked by the plugin.

 

= New-command plugin tutorial (TimePlugin) =

In this section we are going to write a plugin which implements a new command for SPADS. Such plugins are configurable plugins like the one we wrote just before, with 2 additional files to configure the new commands. This plugin will give current time when someone types <code>!time</code>.

== Preparing the template ==

This time we need to download 4 files to prepare our plugin: [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPlugin.pm the new-command plugin template], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPlugin.conf the associated configuration file example], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginHelp.dat the help file example] and [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginCmd.conf the commands rights configuration file example].

As usual, we rename these files to match our plugin name: <code>MyNewCommandPlugin</code> --> <code>TimePlugin</code>. Then we edit the plugin template <code>TimePlugin.pm</code> and replace <code>MyNewCommandPlugin</code> by <code>TimePlugin</code> in the source code, and we do the same for the plugin configuration template <code>TimePlugin.conf</code>, so that the <code>commandsFile</code> and <code>helpFile</code> settings are consistent with the files we just renamed.

Then we can edit our command rights requirements configuration file: <code>TimePluginCmd.conf</code>. This file uses the same syntax as the standard SPADS <code>commands.conf</code> file. The template provides a default command <code>myCommand</code> with no requirement. We will just rename this command to <code>time</code>:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# Anyone can call our command from anywhere
[time]
::|0:
|}
Now we need to write the help information for our new command. This is done in the file <code>TimePluginHelp.dat</code>. This file uses the same syntax as the standard SPADS <code>help.dat</code> file, and the template provides a help example for a command <code>myCommand</code> as a syntax reminder. After each command declaration, the first line is the command syntax description, and the other lines are optional usage examples. Let's replace this help example with our own help information for our basic <code>!time</code> command:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
[time]
<nowiki>!</nowiki>time - This command just prints current time
|}

== Writing plugin code ==

The new-command plugin template that we used to initialize our plugin already defines a new command named <code>myCommand</code>, so all we have to do is to edit our plugin file ( <code>TimePlugin.pm</code> ) and replace this command by our own <code>time</code> command:

First, let's modify the code which sets up the new SPADS command handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addSpadsCommandHandler-handlers-replace-0 addSpadsCommandHandler]. This call is located in the plugin constructor. We edit it so that it becomes:
<syntaxhighlight lang="perl">
[...]
# We declare our new command and the associated handler
addSpadsCommandHandler({time => \&hSpadsTime});
[...]
</syntaxhighlight>
We must modify the same way the code which removes this SPADS handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#removeSpadsCommandHandler-commands removeSpadsCommandHandler] in the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback:
<syntaxhighlight lang="perl">
[...]
# We remove our new command handler
removeSpadsCommandHandler(['time']);
[...]
</syntaxhighlight>
Finally, we must replace the handler example <code>hMyCommand</code> by our own handler <code>hSpadsTime</code>. In order to answer to the user issuing the command, we can use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#answer-message answer], which will send an answer message to the user in the same way he sent the command (private message, battle lobby...).

Here is an implementation example for this basic command:
<syntaxhighlight lang="perl">
# This is the handler for our new command
sub hSpadsTime {
my ($source,$user,$p_params,$checkOnly)=@_;

# time is a basic command, we have nothing to check in case of callvote
return 1 if($checkOnly);

my @time = localtime();
@time = map(sprintf("%02d",$_),@time);

answer("Current local time: $time[2]:$time[1]:$time[0]");
}
</syntaxhighlight>

Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/TimePlugin.pm this fully functional TimePlugin] plugin, and its associated [http://planetspads.free.fr/spads/plugins/tutorials/TimePlugin.conf configuration file], [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginCmd.conf command rights configuration file] and [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginHelp.dat command help file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module and the plugin help file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the 2 configuration files in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: <code>!plugin TimePlugin load</code>. And finally, we can try to say !time in a private message to SPADS or in the battle lobby, and SPADS should answer giving current local time. Our <code>!time</code> command help should also appear in <code>!help</code> and <code>!help time</code> outputs.

[[Category:SPADS]]

SPADS plugin development

2021-01-28T13:18:51Z

Bibim: /* Preparing the template */

SPADS plugin development

2021-01-28T13:17:14Z

Bibim: /* Writing plugin code */

= Introduction =

SPADS is an autohost system coded in Perl, it supports both Perl and Python plugins. This tutorial deals with Perl plugin development only (for Python plugin development another tutorial is available [https://springrts.com/wiki/SPADS_plugin_development_(Python) here]).

SPADS plugins are object-oriented modules. It is strongly recommended to already know Perl basics before starting Perl plugin development (a brief introduction to Perl is available [https://perldoc.perl.org/perlintro here]).

 
= 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 [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] (the <code>.py</code> files must be ignored for this tutorial, these are the Python versions of the templates).

Our first plugin will be very basic, so we will use the simplest template: <code>MySimplePlugin.pm</code>. 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 <code>HelloWorld</code>. We have to rename the downloaded template from <code>MySimplePlugin.pm</code> to <code>HelloWorld.pm</code>, and edit it to replace <code>MySimplePlugin</code> by <code>HelloWorld</code> 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 <code>spads.conf</code> configuration file and reload SPADS configuration).

We have to move our new plugin (<code>HelloWorld.pm</code>) 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): <code>!plugin HelloWorld load</code>. SPADS should answer <code>Loaded plugin HelloWorld.</code>, 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-self-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 <code>onPrivateMsg</code> callback, which will answer <code>Hello World</code> to anyone saying <code>Hello</code> in a private message to SPADS:
<syntaxhighlight lang="perl">
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;

}</syntaxhighlight>

All we have to do now is adding this callback declaration in our <code>HelloWorld.pm</code> 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: <code>!plugin HelloWorld reload</code>. SPADS should answer <code>Reloaded plugin HelloWorld.</code>, which indicates the plugin has been reloaded successfully.

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

 
= Configurable plugin tutorial (ForbiddenWords) =

In this section we are going to write our first configurable SPADS plugin (a configurable plugin has its own configuration file, named after the plugin name but with <code>.conf</code> extension). This plugin will monitor all messages said by players in the battle lobby, and will kick players who use swear words.

== Specifying our configuration parameters ==

The first step of writing a configurable plugin is to choose how we will configure it. In our example, we will use 2 configuration parameters: <code>words</code> will contain the list of forbidden words, and <code>immuneLevel</code> will contain the minimum autohost access level to be immune regarding these forbidden words checks.

We choose to make <code>words</code> a global setting (unmodifiable, not impacted by preset change), and <code>immuneLevel</code> a preset setting (modifiable, can be impacted by preset change). The <code>words</code> global setting will have no restriction (can be empty, can contain any character...), whereas the <code>immuneLevel</code> preset setting will only be allowed to be an integer or integer range.

== Preparing the template ==

Once we have a clear view of our configuration settings, we can start adapting the template for our needs. Since we are making a configurable plugin, this time we will download [http://planetspads.free.fr/spads/plugins/templates/commented/MyConfigurablePlugin.pm the configurable plugin template] and its associated [http://planetspads.free.fr/spads/plugins/templates/commented/MyConfigurablePlugin.conf configuration file example].

First, let's take a look at the configuration file example. This is a just a basic configuration file containing one global setting example and one preset setting example. Let's modify this file to match the configuration we chose as follows (don't forget to rename the file from <code>MyConfigurablePlugin.conf</code> to <code>ForbiddenWords.conf</code> also):
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# This is our global setting (can't be changed without reloading the configuration)
words:ass;asshole;bastard;bitch;cunt;fuck;motherfucker;shit;whore

# We must define our preset setting in the default preset at least
[default]

# This is our preset setting, which can be changed with "!plugin ... set ..."
# or by loading a preset.
# "100" is the default value, and any integer between 0 and 140 is allowed
immuneLevel:100|0-140
|}
Then we must prepare the plugin template itself, by renaming it from <code>MyConfigurablePlugin.pm</code> to <code>ForbiddenWords.pm</code> and editing it to replace <code>MyConfigurablePlugin</code> by <code>ForbiddenWords</code> in the source code. We must also adapt the template so that it uses the configuration settings we chose. This is done by modifying the <code>%globalPluginParams</code> and <code>%presetPluginParam</code> declarations as follows:
<syntaxhighlight lang="perl">
# We define one global setting "words" and one preset setting "immuneLevel".
# "words" has no type associated (no restriction on allowed values)
# "immuneLevel" must be an integer or an integer range
# (check %paramTypes hash in SpadsConf.pm for a complete list of allowed
# setting types)
my %globalPluginParams = ( words => [] );
my %presetPluginParams = ( immuneLevel => ['integer','integerRange'] );
</syntaxhighlight>

== Writing plugin code ==

We want our plugin to react to messages said in the battle lobby. There is no dedicated callback for this event in [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html SPADS plugin API documentation], so we have to set up our own handler on the [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#SAIDBATTLE:server SAIDBATTLE lobby command]. To do so we have to call the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addLobbyCommandHandler-handlers-priority-caller addLobbyCommandHandler]. We will call this function at the end of our plugin constructor as follows, so that it will be set up directly when the plugin is loaded:
<syntaxhighlight lang="perl">
[...]

# We set up a lobby command handler on SAIDBATTLE
addLobbyCommandHandler({SAIDBATTLE => \&hLobbySaidBattle});

# We return the instantiated plugin
return $self;

}
</syntaxhighlight>
However, if SPADS is disconnected from the lobby due to network problems for example, all lobby handlers are automatically removed. So we must re-add them each time we connect to lobby server. This can be done using the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onLobbyConnected-self-lobbyInterface onLobbyConnected] event-based callback as follows:
<syntaxhighlight lang="perl">
# This callback is called each time we (re)connect to the lobby server
sub onLobbyConnected {

# When we are disconnected from the lobby server, all lobby command
# handlers are automatically removed, so we (re)set up our command
# handler here.
addLobbyCommandHandler({SAIDBATTLE => \&hLobbySaidBattle});

}
</syntaxhighlight>
Also, it is a good practice to remove any handler we have added when the plugin is unloaded. To do so we must implement the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback as follows:
<syntaxhighlight lang="perl">
# This callback is called when the plugin is unloaded
sub onUnload {

# We remove our lobby command handler when the plugin is unloaded
removeLobbyCommandHandler(['SAIDBATTLE']);

}
</syntaxhighlight>
Finally, we have to implement our <code>SAIDBATTLE</code> handler <code>hLobbySaidBattle</code>. In this handler we need to perform following operations:
* skip processing if the user is the autohost itself: we need to access SPADS configuration to compare the user name with the [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:lobbyLogin lobbyLogin] setting value. So we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getSpadsConf getSpadsConf].
* perform processing according to our configuration (<code>words</code> and <code>immuneLevel</code> settings): we need to access our plugin configuration, so we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getPluginConf-pluginName-caller getPluginConf].
* retrieve the autohost access level of the user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getUserAccessLevel-user getUserAccessLevel]
* send a message to the battle lobby when we kick someone: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#sayBattle-message sayBattle].
* send a [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#KICKFROMBATTLE:client KICKFROMBATTLE] lobby command to kick a user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#queueLobbyCommand-lobbyCommand queueLobbyCommand].

Here is a commented implementation example of this <code>hLobbySaidBattle</code> handler, which will kick any non-privileged user saying a forbidden word in the battle lobby:
<syntaxhighlight lang="perl">
# This is the handler we set up on SAIDBATTLE lobby command.
# It is called each time a player says something in the battle lobby.
sub hLobbySaidBattle {

# $command is the lobby command name (SAIDBATTLE)
# $user is the name of the user who said something in the battle lobby
# $message is the message said in the battle lobby
my ($command,$user,$message)=@_;

# First we check it's not a message from SPADS (so we don't kick ourself)
my $p_spadsConf=getSpadsConf();
return if($user eq $p_spadsConf->{lobbyLogin});

# Then we check the user isn't a privileged user
# (autohost access level >= immuneLevel)
my $p_conf=getPluginConf();
return if(getUserAccessLevel($user) >= $p_conf->{immuneLevel});

# We put the forbidden words in a array
my @forbiddenWords=split(/;/,$p_conf->{words});

# We test each forbidden word
foreach my $forbiddenWord (@forbiddenWords) {

# If the message contains the forbidden word (case insensitive)
if($message =~ /\b$forbiddenWord\b/i) {

# Then we kick the user from the battle lobby
sayBattle("Kicking $user from battle (watch your language!)");
queueLobbyCommand(["KICKFROMBATTLE",$user]);

# We quit the foreach loop (no need to test other forbidden word)
last;

}

}

}
</syntaxhighlight>
Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/ForbiddenWords.pm this fully functional ForbiddenWords] plugin and [http://planetspads.free.fr/spads/plugins/tutorials/ForbiddenWords.conf its associated configuration file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the associated configuration file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: <code>!plugin ForbiddenWords load</code>. And finally, as an unprivileged user we can try to say some forbidden words in the battle lobby and we should get kicked by the plugin.

 

= New-command plugin tutorial (TimePlugin) =

In this section we are going to write a plugin which implements a new command for SPADS. Such plugins are configurable plugins like the one we wrote just before, with 2 additional files to configure the new commands. This plugin will give current time when someone types <code>!time</code>.

== Preparing the template ==

This time we need to download 4 files to prepare our plugin: [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPlugin.pm the new-command plugin template], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPlugin.conf the associated configuration file example], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginHelp.dat the help file example] and [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginCmd.conf the commands rights configuration file example].

As usual, we rename these files to match our plugin name: <code>MyNewCommandPlugin</code> --> <code>TimePlugin</code>. Then we edit the plugin template <code>TimePlugin.pm</code> and replace <code>MyNewCommandPlugin</code> by <code>TimePlugin</code> in the source code, and we do the same for the plugin configuration template <code>TimePlugin.conf</code>, so that the <code>commandsFile</code> and <code>helpFile</code> settings are consistent with the files we just renamed.

Then we can edit our command rights requirements configuration file: <code>TimePluginCmd.conf</code>. This file uses the same syntax as the standard SPADS <code>commands.conf</code> file. The template provides a default command <code>myCommand</code> with no requirement. We will just rename this command to <code>time</code>:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# Anyone can call our command from anywhere
[time]
::|0:
|}
Now we need to write the help information for our new command. This is done in the file <code>TimePluginHelp.dat</code>. This file uses the same syntax as the standard SPADS <code>help.dat</code> file, and the template provides a help example for a command <code>myCommand</code> as a syntax reminder. After each command declaration, the first line is the command syntax description, and the other lines are optional usage examples. Let's replace this help example with our own help information for our basic <code>!time</code> command:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
[time]
<nowiki>!</nowiki>time - This command just prints current time
|}
== Writing plugin code ==

The new-command plugin template that we used to initialize our plugin already defines a new command named <code>myCommand</code>, so all we have to do is to edit our plugin file ( <code>TimePlugin.pm</code> ) and replace this command by our own <code>time</code> command:

First, let's modify the code which sets up the new SPADS command handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addSpadsCommandHandler-handlers-replace-0 addSpadsCommandHandler]. This call is located in the plugin constructor. We edit it so that it becomes:
<syntaxhighlight lang="perl">
[...]
# We declare our new command and the associated handler
addSpadsCommandHandler({time => \&hSpadsTime});
[...]
</syntaxhighlight>
We must modify the same way the code which removes this SPADS handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#removeSpadsCommandHandler-commands removeSpadsCommandHandler] in the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback:
<syntaxhighlight lang="perl">
[...]
# We remove our new command handler
removeSpadsCommandHandler(['time']);
[...]
</syntaxhighlight>
Finally, we must replace the handler example <code>hMyCommand</code> by our own handler <code>hSpadsTime</code>. In order to answer to the user issuing the command, we can use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#answer-message answer], which will send an answer message to the user in the same way he sent the command (private message, battle lobby...).

Here is an implementation example for this basic command:
<syntaxhighlight lang="perl">
# This is the handler for our new command
sub hSpadsTime {
my ($source,$user,$p_params,$checkOnly)=@_;

# time is a basic command, we have nothing to check in case of callvote
return 1 if($checkOnly);

my @time = localtime();
@time = map(sprintf("%02d",$_),@time);

answer("Current local time: $time[2]:$time[1]:$time[0]");
}
</syntaxhighlight>

Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/TimePlugin.pm this fully functional TimePlugin] plugin, and its associated [http://planetspads.free.fr/spads/plugins/tutorials/TimePlugin.conf configuration file], [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginCmd.conf command rights configuration file] and [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginHelp.dat command help file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module and the plugin help file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the 2 configuration files in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: <code>!plugin TimePlugin load</code>. And finally, we can try to say !time in a private message to SPADS or in the battle lobby, and SPADS should answer giving current local time. Our <code>!time</code> command help should also appear in <code>!help</code> and <code>!help time</code> outputs.

[[Category:SPADS]]

SPADS plugin development

2021-01-28T13:15:31Z

Bibim: /* Preparing the template */

= Introduction =

SPADS is an autohost system coded in Perl, it supports both Perl and Python plugins. This tutorial deals with Perl plugin development only (for Python plugin development another tutorial is available [https://springrts.com/wiki/SPADS_plugin_development_(Python) here]).

SPADS plugins are object-oriented modules. It is strongly recommended to already know Perl basics before starting Perl plugin development (a brief introduction to Perl is available [https://perldoc.perl.org/perlintro here]).

 
= 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 [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] (the <code>.py</code> files must be ignored for this tutorial, these are the Python versions of the templates).

Our first plugin will be very basic, so we will use the simplest template: <code>MySimplePlugin.pm</code>. 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 <code>HelloWorld</code>. We have to rename the downloaded template from <code>MySimplePlugin.pm</code> to <code>HelloWorld.pm</code>, and edit it to replace <code>MySimplePlugin</code> by <code>HelloWorld</code> 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 <code>spads.conf</code> configuration file and reload SPADS configuration).

We have to move our new plugin (<code>HelloWorld.pm</code>) 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): <code>!plugin HelloWorld load</code>. SPADS should answer <code>Loaded plugin HelloWorld.</code>, 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-self-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 <code>onPrivateMsg</code> callback, which will answer <code>Hello World</code> to anyone saying <code>Hello</code> in a private message to SPADS:
<syntaxhighlight lang="perl">
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;

}</syntaxhighlight>

All we have to do now is adding this callback declaration in our <code>HelloWorld.pm</code> 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: <code>!plugin HelloWorld reload</code>. SPADS should answer <code>Reloaded plugin HelloWorld.</code>, which indicates the plugin has been reloaded successfully.

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

 
= Configurable plugin tutorial (ForbiddenWords) =

In this section we are going to write our first configurable SPADS plugin (a configurable plugin has its own configuration file, named after the plugin name but with <code>.conf</code> extension). This plugin will monitor all messages said by players in the battle lobby, and will kick players who use swear words.

== Specifying our configuration parameters ==

The first step of writing a configurable plugin is to choose how we will configure it. In our example, we will use 2 configuration parameters: <code>words</code> will contain the list of forbidden words, and <code>immuneLevel</code> will contain the minimum autohost access level to be immune regarding these forbidden words checks.

We choose to make <code>words</code> a global setting (unmodifiable, not impacted by preset change), and <code>immuneLevel</code> a preset setting (modifiable, can be impacted by preset change). The <code>words</code> global setting will have no restriction (can be empty, can contain any character...), whereas the <code>immuneLevel</code> preset setting will only be allowed to be an integer or integer range.

== Preparing the template ==

Once we have a clear view of our configuration settings, we can start adapting the template for our needs. Since we are making a configurable plugin, this time we will download [http://planetspads.free.fr/spads/plugins/templates/commented/MyConfigurablePlugin.pm the configurable plugin template] and its associated [http://planetspads.free.fr/spads/plugins/templates/commented/MyConfigurablePlugin.conf configuration file example].

First, let's take a look at the configuration file example. This is a just a basic configuration file containing one global setting example and one preset setting example. Let's modify this file to match the configuration we chose as follows (don't forget to rename the file from <code>MyConfigurablePlugin.conf</code> to <code>ForbiddenWords.conf</code> also):
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# This is our global setting (can't be changed without reloading the configuration)
words:ass;asshole;bastard;bitch;cunt;fuck;motherfucker;shit;whore

# We must define our preset setting in the default preset at least
[default]

# This is our preset setting, which can be changed with "!plugin ... set ..."
# or by loading a preset.
# "100" is the default value, and any integer between 0 and 140 is allowed
immuneLevel:100|0-140
|}
Then we must prepare the plugin template itself, by renaming it from <code>MyConfigurablePlugin.pm</code> to <code>ForbiddenWords.pm</code> and editing it to replace <code>MyConfigurablePlugin</code> by <code>ForbiddenWords</code> in the source code. We must also adapt the template so that it uses the configuration settings we chose. This is done by modifying the <code>%globalPluginParams</code> and <code>%presetPluginParam</code> declarations as follows:
<syntaxhighlight lang="perl">
# We define one global setting "words" and one preset setting "immuneLevel".
# "words" has no type associated (no restriction on allowed values)
# "immuneLevel" must be an integer or an integer range
# (check %paramTypes hash in SpadsConf.pm for a complete list of allowed
# setting types)
my %globalPluginParams = ( words => [] );
my %presetPluginParams = ( immuneLevel => ['integer','integerRange'] );
</syntaxhighlight>

== Writing plugin code ==

We want our plugin to react to messages said in the battle lobby. There is no dedicated callback for this event in [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html SPADS plugin API documentation], so we have to set up our own handler on the [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#SAIDBATTLE:server SAIDBATTLE lobby command]. To do so we have to call the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addLobbyCommandHandler-handlers-priority-caller addLobbyCommandHandler]. We will call this function at the end of our plugin constructor as follows, so that it will be set up directly when the plugin is loaded:
<syntaxhighlight lang="perl">
[...]

# We set up a lobby command handler on SAIDBATTLE
addLobbyCommandHandler({SAIDBATTLE => \&hLobbySaidBattle});

# We return the instantiated plugin
return $self;

}
</syntaxhighlight>
However, if SPADS is disconnected from the lobby due to network problems for example, all lobby handlers are automatically removed. So we must re-add them each time we connect to lobby server. This can be done using the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onLobbyConnected-self-lobbyInterface onLobbyConnected] event-based callback as follows:
<syntaxhighlight lang="perl">
# This callback is called each time we (re)connect to the lobby server
sub onLobbyConnected {

# When we are disconnected from the lobby server, all lobby command
# handlers are automatically removed, so we (re)set up our command
# handler here.
addLobbyCommandHandler({SAIDBATTLE => \&hLobbySaidBattle});

}
</syntaxhighlight>
Also, it is a good practice to remove any handler we have added when the plugin is unloaded. To do so we must implement the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback as follows:
<syntaxhighlight lang="perl">
# This callback is called when the plugin is unloaded
sub onUnload {

# We remove our lobby command handler when the plugin is unloaded
removeLobbyCommandHandler(['SAIDBATTLE']);

}
</syntaxhighlight>
Finally, we have to implement our <code>SAIDBATTLE</code> handler <code>hLobbySaidBattle</code>. In this handler we need to perform following operations:
* skip processing if the user is the autohost itself: we need to access SPADS configuration to compare the user name with the [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:lobbyLogin lobbyLogin] setting value. So we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getSpadsConf getSpadsConf].
* perform processing according to our configuration (<code>words</code> and <code>immuneLevel</code> settings): we need to access our plugin configuration, so we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getPluginConf-pluginName-caller getPluginConf].
* retrieve the autohost access level of the user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getUserAccessLevel-user getUserAccessLevel]
* send a message to the battle lobby when we kick someone: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#sayBattle-message sayBattle].
* send a [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#KICKFROMBATTLE:client KICKFROMBATTLE] lobby command to kick a user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#queueLobbyCommand-lobbyCommand queueLobbyCommand].

Here is a commented implementation example of this <code>hLobbySaidBattle</code> handler, which will kick any non-privileged user saying a forbidden word in the battle lobby:
<syntaxhighlight lang="perl">
# This is the handler we set up on SAIDBATTLE lobby command.
# It is called each time a player says something in the battle lobby.
sub hLobbySaidBattle {

# $command is the lobby command name (SAIDBATTLE)
# $user is the name of the user who said something in the battle lobby
# $message is the message said in the battle lobby
my ($command,$user,$message)=@_;

# First we check it's not a message from SPADS (so we don't kick ourself)
my $p_spadsConf=getSpadsConf();
return if($user eq $p_spadsConf->{lobbyLogin});

# Then we check the user isn't a privileged user
# (autohost access level >= immuneLevel)
my $p_conf=getPluginConf();
return if(getUserAccessLevel($user) >= $p_conf->{immuneLevel});

# We put the forbidden words in a array
my @forbiddenWords=split(/;/,$p_conf->{words});

# We test each forbidden word
foreach my $forbiddenWord (@forbiddenWords) {

# If the message contains the forbidden word (case insensitive)
if($message =~ /\b$forbiddenWord\b/i) {

# Then we kick the user from the battle lobby
sayBattle("Kicking $user from battle (watch your language!)");
queueLobbyCommand(["KICKFROMBATTLE",$user]);

# We quit the foreach loop (no need to test other forbidden word)
last;

}

}

}
</syntaxhighlight>
Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/ForbiddenWords.pm this fully functional ForbiddenWords] plugin and [http://planetspads.free.fr/spads/plugins/tutorials/ForbiddenWords.conf its associated configuration file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the associated configuration file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: <code>!plugin ForbiddenWords load</code>. And finally, as an unprivileged user we can try to say some forbidden words in the battle lobby and we should get kicked by the plugin.

 

= New-command plugin tutorial (TimePlugin) =

In this section we are going to write a plugin which implements a new command for SPADS. Such plugins are configurable plugins like the one we wrote just before, with 2 additional files to configure the new commands. This plugin will give current time when someone types <code>!time</code>.

== Preparing the template ==

This time we need to download 4 files to prepare our plugin: [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPlugin.pm the new-command plugin template], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPlugin.conf the associated configuration file example], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginHelp.dat the help file example] and [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginCmd.conf the commands rights configuration file example].

As usual, we rename these files to match our plugin name: <code>MyNewCommandPlugin</code> --> <code>TimePlugin</code>. Then we edit the plugin template <code>TimePlugin.pm</code> and replace <code>MyNewCommandPlugin</code> by <code>TimePlugin</code> in the source code, and we do the same for the plugin configuration template <code>TimePlugin.conf</code>, so that the <code>commandsFile</code> and <code>helpFile</code> settings are consistent with the files we just renamed.

Then we can edit our command rights requirements configuration file: <code>TimePluginCmd.conf</code>. This file uses the same syntax as the standard SPADS <code>commands.conf</code> file. The template provides a default command <code>myCommand</code> with no requirement. We will just rename this command to <code>time</code>:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# Anyone can call our command from anywhere
[time]
::|0:
|}
Now we need to write the help information for our new command. This is done in the file <code>TimePluginHelp.dat</code>. This file uses the same syntax as the standard SPADS <code>help.dat</code> file, and the template provides a help example for a command <code>myCommand</code> as a syntax reminder. After each command declaration, the first line is the command syntax description, and the other lines are optional usage examples. Let's replace this help example with our own help information for our basic <code>!time</code> command:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
[time]
<nowiki>!</nowiki>time - This command just prints current time
|}
== Writing plugin code ==

The new-command plugin template that we used to initialize our plugin already defines a new command named <code>myCommand</code>, so all we have to do is to edit our plugin file ( <code>TimePlugin.pm</code> ) and replace this command by our own <code>time</code> command:

First, let's modify the code which sets up the new SPADS command handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addSpadsCommandHandler-handlers-replace-0 addSpadsCommandHandler]. This call is located in the plugin constructor. We edit it so that it becomes:
<syntaxhighlight lang="perl">
[...]
# We declare our new command and the associated handler
addSpadsCommandHandler({time => \&hSpadsTime});
[...]
</syntaxhighlight>
We must modify the same way the code which removes this SPADS handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#removeSpadsCommandHandler-commands removeSpadsCommandHandler] in the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback:
<syntaxhighlight lang="perl">
[...]
# We remove our new command handler
removeSpadsCommandHandler(['time']);
[...]
</syntaxhighlight>
Finally, we must replace the handler example <code>hMyCommand</code> by our own handler <code>hSpadsTime</code>. In order to answer to the user issuing the command, we can use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#answer-message answer], which will send an answer message to the user in the same way he sent the command (private message, battle lobby...).

Here is an implementation example for this basic command:
<syntaxhighlight lang="perl">
# This is the handler for our new command
sub hSpadsTime {
my ($source,$user,$p_params,$checkOnly)=@_;

# time is a basic command, we have nothing to check in case of callvote
return 1 if($checkOnly);

my @time = localtime();
@time = map(sprintf("%02d",$_),@time);

answer("Current local time: $time[2]:$time[1]:$time[0]");
}
</syntaxhighlight>

Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/TimePlugin.pm this fully functional TimePlugin] plugin, and its associated [http://planetspads.free.fr/spads/plugins/tutorials/TimePlugin.conf configuration file], [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginCmd.conf command rights configuration file] and [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginHelp.dat command help file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module and the plugin help file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the 2 configuration files in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: <code>!plugin TimePlugin load</code>. And finally, we can try to say !time in a private message to SPADS or in the battle lobby, and SPADS should answer giving current local time. Our <code>!time</code> command help should also appear in <code>!help</code> and <code>!help time</code> outputs.

[[Category:SPADS]]

SPADS plugin development

2021-01-28T13:15:00Z

Bibim: /* Writing plugin code */

= Introduction =

SPADS is an autohost system coded in Perl, it supports both Perl and Python plugins. This tutorial deals with Perl plugin development only (for Python plugin development another tutorial is available [https://springrts.com/wiki/SPADS_plugin_development_(Python) here]).

SPADS plugins are object-oriented modules. It is strongly recommended to already know Perl basics before starting Perl plugin development (a brief introduction to Perl is available [https://perldoc.perl.org/perlintro here]).

 
= 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 [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] (the <code>.py</code> files must be ignored for this tutorial, these are the Python versions of the templates).

Our first plugin will be very basic, so we will use the simplest template: <code>MySimplePlugin.pm</code>. 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 <code>HelloWorld</code>. We have to rename the downloaded template from <code>MySimplePlugin.pm</code> to <code>HelloWorld.pm</code>, and edit it to replace <code>MySimplePlugin</code> by <code>HelloWorld</code> 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 <code>spads.conf</code> configuration file and reload SPADS configuration).

We have to move our new plugin (<code>HelloWorld.pm</code>) 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): <code>!plugin HelloWorld load</code>. SPADS should answer <code>Loaded plugin HelloWorld.</code>, 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-self-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 <code>onPrivateMsg</code> callback, which will answer <code>Hello World</code> to anyone saying <code>Hello</code> in a private message to SPADS:
<syntaxhighlight lang="perl">
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;

}</syntaxhighlight>

All we have to do now is adding this callback declaration in our <code>HelloWorld.pm</code> 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: <code>!plugin HelloWorld reload</code>. SPADS should answer <code>Reloaded plugin HelloWorld.</code>, which indicates the plugin has been reloaded successfully.

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

 
= Configurable plugin tutorial (ForbiddenWords) =

In this section we are going to write our first configurable SPADS plugin (a configurable plugin has its own configuration file, named after the plugin name but with <code>.conf</code> extension). This plugin will monitor all messages said by players in the battle lobby, and will kick players who use swear words.

== Specifying our configuration parameters ==

The first step of writing a configurable plugin is to choose how we will configure it. In our example, we will use 2 configuration parameters: <code>words</code> will contain the list of forbidden words, and <code>immuneLevel</code> will contain the minimum autohost access level to be immune regarding these forbidden words checks.

We choose to make <code>words</code> a global setting (unmodifiable, not impacted by preset change), and <code>immuneLevel</code> a preset setting (modifiable, can be impacted by preset change). The <code>words</code> global setting will have no restriction (can be empty, can contain any character...), whereas the <code>immuneLevel</code> preset setting will only be allowed to be an integer or integer range.

== Preparing the template ==

Once we have a clear view of our configuration settings, we can start adapting the template for our needs. Since we are making a configurable plugin, this time we will download [http://planetspads.free.fr/spads/plugins/templates/commented/MyConfigurablePlugin.pm the configurable plugin template] and its associated [http://planetspads.free.fr/spads/plugins/templates/commented/MyConfigurablePlugin.conf configuration file example].

First, let's take a look at the configuration file example. This is a just a basic configuration file containing one global setting example and one preset setting example. Let's modify this file to match the configuration we chose as follows (don't forget to rename the file from <code>MyConfigurablePlugin.conf</code> to <code>ForbiddenWords.conf</code> also):
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# This is our global setting (can't be changed without reloading the configuration)
words:ass;asshole;bastard;bitch;cunt;fuck;motherfucker;shit;whore

# We must define our preset setting in the default preset at least
[default]

# This is our preset setting, which can be changed with "!plugin ... set ..."
# or by loading a preset.
# "100" is the default value, and any integer between 0 and 140 is allowed
immuneLevel:100|0-140
|}
Then we must prepare the plugin template itself, by renaming it from <code>MyConfigurablePlugin.pm</code> to <code>ForbiddenWords.pm</code> and editing it to replace <code>MyConfigurablePlugin</code> by <code>ForbiddenWords</code> in the source code. We must also adapt the template so that it uses the configuration settings we chose. This is done by modifying the <code>%globalPluginParams</code> and <code>%presetPluginParam</code> declarations as follows:
<syntaxhighlight lang="perl">
# We define one global setting "words" and one preset setting "immuneLevel".
# "words" has no type associated (no restriction on allowed values)
# "immuneLevel" must be an integer or an integer range
# (check %paramTypes hash in SpadsConf.pm for a complete list of allowed
# setting types)
my %globalPluginParams = ( words => [] );
my %presetPluginParams = ( immuneLevel => ['integer','integerRange'] );
</syntaxhighlight>

== Writing plugin code ==

We want our plugin to react to messages said in the battle lobby. There is no dedicated callback for this event in [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html SPADS plugin API documentation], so we have to set up our own handler on the [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#SAIDBATTLE:server SAIDBATTLE lobby command]. To do so we have to call the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addLobbyCommandHandler-handlers-priority-caller addLobbyCommandHandler]. We will call this function at the end of our plugin constructor as follows, so that it will be set up directly when the plugin is loaded:
<syntaxhighlight lang="perl">
[...]

# We set up a lobby command handler on SAIDBATTLE
addLobbyCommandHandler({SAIDBATTLE => \&hLobbySaidBattle});

# We return the instantiated plugin
return $self;

}
</syntaxhighlight>
However, if SPADS is disconnected from the lobby due to network problems for example, all lobby handlers are automatically removed. So we must re-add them each time we connect to lobby server. This can be done using the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onLobbyConnected-self-lobbyInterface onLobbyConnected] event-based callback as follows:
<syntaxhighlight lang="perl">
# This callback is called each time we (re)connect to the lobby server
sub onLobbyConnected {

# When we are disconnected from the lobby server, all lobby command
# handlers are automatically removed, so we (re)set up our command
# handler here.
addLobbyCommandHandler({SAIDBATTLE => \&hLobbySaidBattle});

}
</syntaxhighlight>
Also, it is a good practice to remove any handler we have added when the plugin is unloaded. To do so we must implement the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback as follows:
<syntaxhighlight lang="perl">
# This callback is called when the plugin is unloaded
sub onUnload {

# We remove our lobby command handler when the plugin is unloaded
removeLobbyCommandHandler(['SAIDBATTLE']);

}
</syntaxhighlight>
Finally, we have to implement our <code>SAIDBATTLE</code> handler <code>hLobbySaidBattle</code>. In this handler we need to perform following operations:
* skip processing if the user is the autohost itself: we need to access SPADS configuration to compare the user name with the [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:lobbyLogin lobbyLogin] setting value. So we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getSpadsConf getSpadsConf].
* perform processing according to our configuration (<code>words</code> and <code>immuneLevel</code> settings): we need to access our plugin configuration, so we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getPluginConf-pluginName-caller getPluginConf].
* retrieve the autohost access level of the user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getUserAccessLevel-user getUserAccessLevel]
* send a message to the battle lobby when we kick someone: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#sayBattle-message sayBattle].
* send a [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#KICKFROMBATTLE:client KICKFROMBATTLE] lobby command to kick a user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#queueLobbyCommand-lobbyCommand queueLobbyCommand].

Here is a commented implementation example of this <code>hLobbySaidBattle</code> handler, which will kick any non-privileged user saying a forbidden word in the battle lobby:
<syntaxhighlight lang="perl">
# This is the handler we set up on SAIDBATTLE lobby command.
# It is called each time a player says something in the battle lobby.
sub hLobbySaidBattle {

# $command is the lobby command name (SAIDBATTLE)
# $user is the name of the user who said something in the battle lobby
# $message is the message said in the battle lobby
my ($command,$user,$message)=@_;

# First we check it's not a message from SPADS (so we don't kick ourself)
my $p_spadsConf=getSpadsConf();
return if($user eq $p_spadsConf->{lobbyLogin});

# Then we check the user isn't a privileged user
# (autohost access level >= immuneLevel)
my $p_conf=getPluginConf();
return if(getUserAccessLevel($user) >= $p_conf->{immuneLevel});

# We put the forbidden words in a array
my @forbiddenWords=split(/;/,$p_conf->{words});

# We test each forbidden word
foreach my $forbiddenWord (@forbiddenWords) {

# If the message contains the forbidden word (case insensitive)
if($message =~ /\b$forbiddenWord\b/i) {

# Then we kick the user from the battle lobby
sayBattle("Kicking $user from battle (watch your language!)");
queueLobbyCommand(["KICKFROMBATTLE",$user]);

# We quit the foreach loop (no need to test other forbidden word)
last;

}

}

}
</syntaxhighlight>
Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/ForbiddenWords.pm this fully functional ForbiddenWords] plugin and [http://planetspads.free.fr/spads/plugins/tutorials/ForbiddenWords.conf its associated configuration file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the associated configuration file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: <code>!plugin ForbiddenWords load</code>. And finally, as an unprivileged user we can try to say some forbidden words in the battle lobby and we should get kicked by the plugin.

 

= New-command plugin tutorial (TimePlugin) =

In this section we are going to write a plugin which implements a new command for SPADS. Such plugins are configurable plugins like the one we wrote just before, with 2 additional files to configure the new commands. This plugin will give current time when someone types <code>!time</code>.

== Preparing the template ==

This time we need to download 4 files to prepare our plugin: [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPlugin.pm the new-command plugin template], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPlugin.conf the associated configuration file example], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginHelp.dat the help file example] and [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginCmd.conf the commands rights configuration file example].

As usual, we rename these files to match our plugin name: <code>MyNewCommandPlugin</code> --> <code>TimePlugin</code>. Then we edit the plugin template <code>TimePlugin.pm</code> and replace <code>MyNewCommandPlugin</code> by <code>TimePlugin</code> in the source code, and we do the same for the plugin configuration template <code>TimePlugin.conf</code>, so that the <code>commandsFile</code> and <code>helpFile</code> settings are consistent with the files we just renamed.

Then we can edit our command rights requirements configuration file: <code>TimePluginCmd.conf</code>. This file uses the same syntax as the standard SPADS <code>commands.conf</code> file. The template provides a default command <code>myCommand</code> with no requirement. We will just rename this command to <code>time</code>:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# Anyone can call our command from anywhere
[time]
::|0:
|}
Now we need to write the help information for our new command. This is done in the file <code>TimePluginHelp.dat</code>. This file uses the same syntax as the standard SPADS <code>help.dat</code> file, and the template provides a help example for a command <code>myCommand</code> as a syntax reminder. After each command declaration, the first line is the command syntax description, and the other lines are optional usage examples. Let's replace this help example with our own help information for our basic <code>!time</code> command:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
[time]
<nowiki>!</nowiki>time - This command just prints current time
|}
== Writing plugin code ==

The new-command plugin template that we used to initialize our plugin already defines a new command named <code>myCommand</code>, so all we have to do is to edit our plugin file ( <code>TimePlugin.pm</code> ) and replace this command by our own <code>time</code> command:

First, let's modify the code which sets up the new SPADS command handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addSpadsCommandHandler-handlers-replace-0 addSpadsCommandHandler]. This call is located in the plugin constructor. We edit it so that it becomes:
<syntaxhighlight lang="perl">
[...]
# We declare our new command and the associated handler
addSpadsCommandHandler({time => \&hSpadsTime});
[...]
</syntaxhighlight>
We must modify the same way the code which removes this SPADS handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#removeSpadsCommandHandler-commands removeSpadsCommandHandler] in the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback:
<syntaxhighlight lang="perl">
[...]
# We remove our new command handler
removeSpadsCommandHandler(['time']);
[...]
</syntaxhighlight>
Finally, we must replace the handler example <code>hMyCommand</code> by our own handler <code>hSpadsTime</code>. In order to answer to the user issuing the command, we can use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#answer-message answer], which will send an answer message to the user in the same way he sent the command (private message, battle lobby...).

Here is an implementation example for this basic command:
<syntaxhighlight lang="perl">
# This is the handler for our new command
sub hSpadsTime {
my ($source,$user,$p_params,$checkOnly)=@_;

# time is a basic command, we have nothing to check in case of callvote
return 1 if($checkOnly);

my @time = localtime();
@time = map(sprintf("%02d",$_),@time);

answer("Current local time: $time[2]:$time[1]:$time[0]");
}
</syntaxhighlight>

Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/TimePlugin.pm this fully functional TimePlugin] plugin, and its associated [http://planetspads.free.fr/spads/plugins/tutorials/TimePlugin.conf configuration file], [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginCmd.conf command rights configuration file] and [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginHelp.dat command help file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module and the plugin help file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the 2 configuration files in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: <code>!plugin TimePlugin load</code>. And finally, we can try to say !time in a private message to SPADS or in the battle lobby, and SPADS should answer giving current local time. Our <code>!time</code> command help should also appear in <code>!help</code> and <code>!help time</code> outputs.

[[Category:SPADS]]

SPADS plugin development (Python)

2021-01-28T13:13:01Z

Bibim:

= Introduction =

SPADS is an autohost system coded in Perl, it supports both Perl and Python plugins. This tutorial deals with Python plugin development only (for Perl plugin development another tutorial is available [https://springrts.com/wiki/SPADS_plugin_development here]).

SPADS plugins are object-oriented modules. It is strongly recommended to already know Python basics before starting Python plugin development (a Python tutorial is available [https://docs.python.org/3/tutorial/ here]).

 
= Technical prerequisites =

Python (the Python interpreter and its libraries) must be installed on the system (versions 2.6+ or 3.2+ recommended). The type of installation (32-bit / 64-bit) must be consistent with the Perl version and the Spring engine used for SPADS.

Additionally, in order to allow communication between Perl code (SPADS core) and Python code (SPADS plugins), SPADS uses a Perl module named <code>Inline::Python</code> which must also be installed on the system. It is recommended to install the latest version for SPADS, refer to [https://springrts.com/wiki/SPADS_Inline::Python_installation_guide this guide] for installation.

 

= 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 [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] (the <code>.pm</code> files must be ignored for this tutorial, these are the Perl versions of the templates).

Our first plugin will be very basic, so we will use the simplest template: <code>mysimpleplugin.py</code>. Let's download [http://planetspads.free.fr/spads/plugins/templates/commented/mysimpleplugin.py 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 <code>HelloWorld</code>. We have to rename the downloaded template from <code>mysimpleplugin.py</code> to <code>helloworld.py</code>, and edit it to replace <code>MySimplePlugin</code> by <code>HelloWorld</code> 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 <code>spads.conf</code> configuration file and reload SPADS configuration).

We have to move our new plugin (<code>helloworld.py</code>) 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): <code>!plugin HelloWorld load</code>. SPADS should answer <code>Loaded plugin HelloWorld.</code>, 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-self-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 <code>onPrivateMsg</code> callback, which will answer <code>Hello World</code> to anyone saying <code>Hello</code> in a private message to SPADS:
<syntaxhighlight lang="python">
# This is the callback called each time SPADS receives a private message
# 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
def onPrivateMsg(self,userName,message):

# Here we "fix" strings received from Perl in case
# the Inline::Python module transmits them as byte strings
(userName,message)=spads.fix_string(userName,message)

# We check the message sent by the user is "Hello"
if message == 'Hello':

# We send our wonderful Hello World message
spads.sayPrivate(userName,'Hello World')

# We return 0 because we don't want to filter out private messages
# for other SPADS processing
return 0</syntaxhighlight>

All we have to do now is adding this callback declaration in our <code>helloworld.py</code> file located in SPADS plugins directory. We obtain [http://planetspads.free.fr/spads/plugins/tutorials/helloworld.py 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: <code>!plugin HelloWorld reload</code>. SPADS should answer <code>Reloaded plugin HelloWorld.</code>, which indicates the plugin has been reloaded successfully.

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

 
= Configurable plugin tutorial (ForbiddenWords) =

In this section we are going to write our first configurable SPADS plugin (a configurable plugin has its own configuration file, named after the plugin name but with <code>.conf</code> extension). This plugin will monitor all messages said by players in the battle lobby, and will kick players who use swear words.

== Specifying our configuration parameters ==

The first step of writing a configurable plugin is to choose how we will configure it. In our example, we will use 2 configuration parameters: <code>words</code> will contain the list of forbidden words, and <code>immuneLevel</code> will contain the minimum autohost access level to be immune regarding these forbidden words checks.

We choose to make <code>words</code> a global setting (unmodifiable, not impacted by preset change), and <code>immuneLevel</code> a preset setting (modifiable, can be impacted by preset change). The <code>words</code> global setting will have no restriction (can be empty, can contain any character...), whereas the <code>immuneLevel</code> preset setting will only be allowed to be an integer or integer range.

== Preparing the template ==

Once we have a clear view of our configuration settings, we can start adapting the template for our needs. Since we are making a configurable plugin, this time we will download [http://planetspads.free.fr/spads/plugins/templates/commented/myconfigurableplugin.py the configurable plugin template] and its associated [http://planetspads.free.fr/spads/plugins/templates/commented/MyConfigurablePlugin.conf configuration file example].

First, let's take a look at the configuration file example. This is a just a basic configuration file containing one global setting example and one preset setting example. Let's modify this file to match the configuration we chose as follows (don't forget to rename the file from <code>MyConfigurablePlugin.conf</code> to <code>ForbiddenWords.conf</code> also):
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# This is our global setting (can't be changed without reloading the configuration)
words:ass;asshole;bastard;bitch;cunt;fuck;motherfucker;shit;whore

# We must define our preset setting in the default preset at least
[default]

# This is our preset setting, which can be changed with "!plugin ... set ..."
# or by loading a preset.
# "100" is the default value, and any integer between 0 and 140 is allowed
immuneLevel:100|0-140
|}
Then we must prepare the plugin template itself, by renaming it from <code>myconfigurableplugin.py</code> to <code>forbiddenwords.py</code> and editing it to replace <code>MyConfigurablePlugin</code> by <code>ForbiddenWords</code> in the source code. We must also adapt the template so that it uses the configuration settings we chose. This is done by modifying the <code>globalPluginParams</code> and <code>presetPluginParam</code> declarations as follows:
<syntaxhighlight lang="python">
# We define one global setting "words" and one preset setting "immuneLevel".
# "words" has no type associated (no restriction on allowed values)
# "immuneLevel" must be an integer or an integer range
# (check %paramTypes hash in SpadsConf.pm for a complete list of allowed
# setting types)
globalPluginParams = { 'words': [] }
presetPluginParams = { 'immuneLevel': ['integer','integerRange'] }
</syntaxhighlight>

== Writing plugin code ==

We want our plugin to react to messages said in the battle lobby. There is no dedicated callback for this event in [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html SPADS plugin API documentation], so we have to set up our own handler on the [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#SAIDBATTLE:server SAIDBATTLE lobby command]. To do so we have to call the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addLobbyCommandHandler-handlers-priority-caller addLobbyCommandHandler]. We will call this function at the end of our plugin constructor as follows, so that it will be set up directly when the plugin is loaded:
<syntaxhighlight lang="python">
[...]

# We set up a lobby command handler on SAIDBATTLE
spads.addLobbyCommandHandler({'SAIDBATTLE': hLobbySaidBattle})
</syntaxhighlight>
However, if SPADS is disconnected from the lobby due to network problems for example, all lobby handlers are automatically removed. So we must re-add them each time we connect to lobby server. This can be done using the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onLobbyConnected-self-lobbyInterface onLobbyConnected] event-based callback as follows:
<syntaxhighlight lang="python">
# This callback is called each time we (re)connect to the lobby server
def onLobbyConnected(self,lobbyInterface):

# When we are disconnected from the lobby server, all lobby command
# handlers are automatically removed, so we (re)set up our command
# handler here.
spads.addLobbyCommandHandler({'SAIDBATTLE': hLobbySaidBattle})
</syntaxhighlight>
Also, it is a good practice to remove any handler we have added when the plugin is unloaded. To do so we must implement the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback as follows:
<syntaxhighlight lang="python">
# This callback is called when the plugin is unloaded
def onUnload(self,reason):

# We remove our lobby command handler when the plugin is unloaded
spads.removeLobbyCommandHandler(['SAIDBATTLE'])
</syntaxhighlight>
Finally, we have to implement our <code>SAIDBATTLE</code> handler <code>hLobbySaidBattle</code>. In this handler we need to perform following operations:
* skip processing if the user is the autohost itself: we need to access SPADS configuration to compare the user name with the [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:lobbyLogin lobbyLogin] setting value. So we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getSpadsConf getSpadsConf].
* perform processing according to our configuration (<code>words</code> and <code>immuneLevel</code> settings): we need to access our plugin configuration, so we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getPluginConf-pluginName-caller getPluginConf].
* retrieve the autohost access level of the user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getUserAccessLevel-user getUserAccessLevel]
* send a message to the battle lobby when we kick someone: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#sayBattle-message sayBattle].
* send a [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#KICKFROMBATTLE:client KICKFROMBATTLE] lobby command to kick a user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#queueLobbyCommand-lobbyCommand queueLobbyCommand].

Here is a commented implementation example of this <code>hLobbySaidBattle</code> handler, which will kick any non-privileged user saying a forbidden word in the battle lobby:
<syntaxhighlight lang="python">
# This is the handler we set up on SAIDBATTLE lobby command.
# It is called each time a player says something in the battle lobby.
# command is the lobby command name (SAIDBATTLE)
# user is the name of the user who said something in the battle lobby
# message is the message said in the battle lobby
def hLobbySaidBattle(command,user,message):

# First we "fix" strings received from Perl in case
# the Inline::Python module transmits them as byte strings
(user,message)=spads.fix_string(user,message)

# Here we check it's not a message from SPADS (so we don't kick ourself)
spadsConf = spads.getSpadsConf()
if user == spadsConf['lobbyLogin']:
return

# Then we check the user isn't a privileged user
# (autohost access level >= immuneLevel)
pluginConf = spads.getPluginConf()
if int(spads.getUserAccessLevel(user)) >= int(pluginConf['immuneLevel']):
return

# We put the forbidden words in a list
forbiddenWords = pluginConf['words'].split(';')

# We test each forbidden word
for forbiddenWord in forbiddenWords:

# If the message contains the forbidden word (case insensitive)
if re.search(r'\b' + re.escape(forbiddenWord) + r'\b',message,re.IGNORECASE):

# Then we kick the user from the battle lobby
spads.sayBattle("Kicking %s from battle (watch your language!)" % user)
spads.queueLobbyCommand(["KICKFROMBATTLE",user])

# We quit the foreach loop (no need to test other forbidden word)
break
</syntaxhighlight>

As we are using regular expressions in our plugin code, we must not forget to import the <code>re</code> Python module at the start of our plugin:
<syntaxhighlight lang="python">
# Import the regular expression module to check for forbidden words
import re
</syntaxhighlight>
Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/forbiddenwords.py this fully functional ForbiddenWords] plugin and [http://planetspads.free.fr/spads/plugins/tutorials/ForbiddenWords.conf its associated configuration file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the associated configuration file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: <code>!plugin ForbiddenWords load</code>. And finally, as an unprivileged user we can try to say some forbidden words in the battle lobby and we should get kicked by the plugin.

 

'''/!\ WORK IN PROGRESS /!\'''

= New-command plugin tutorial (TimePlugin) =

In this section we are going to write a plugin which implements a new command for SPADS. Such plugins are configurable plugins like the one we wrote just before, with 2 additional files to configure the new commands. This plugin will give current time when someone types <code>!time</code>.

== Preparing the template ==

This time we need to download 4 files to prepare our plugin: [http://planetspads.free.fr/spads/plugins/templates/commented/mynewcommandplugin.py the new-command plugin template], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPlugin.conf the associated configuration file example], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginHelp.dat the help file example] and [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginCmd.conf the commands rights configuration file example].

As usual, we rename these files to match our plugin name: <code>MyNewCommandPlugin</code> --> <code>TimePlugin</code>. Then we edit the plugin template <code>timeplugin.py</code> and replace <code>MyNewCommandPlugin</code> by <code>TimePlugin</code> in the source code, and we do the same for the plugin configuration template <code>TimePlugin.conf</code>, so that the <code>commandsFile</code> and <code>helpFile</code> settings are consistent with the files we just renamed.

Then we can edit our command rights requirements configuration file: <code>TimePluginCmd.conf</code>. This file uses the same syntax as the standard SPADS <code>commands.conf</code> file. The template provides a default command <code>myCommand</code> with no requirement. We will just rename this command to <code>time</code>:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# Anyone can call our command from anywhere
[time]
::|0:
|}
Now we need to write the help information for our new command. This is done in the file <code>TimePluginHelp.dat</code>. This file uses the same syntax as the standard SPADS <code>help.dat</code> file, and the template provides a help example for a command <code>myCommand</code> as a syntax reminder. After each command declaration, the first line is the command syntax description, and the other lines are optional usage examples. Let's replace this help example with our own help information for our basic <code>!time</code> command:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
[time]
<nowiki>!</nowiki>time - This command just prints current time
|}
== Writing plugin code ==

The new-command plugin template that we used to initialize our plugin already defines a new command named <code>myCommand</code>, so all we have to do is to edit our plugin file ( <code>timeplugin.py</code> ) and replace this command by our own <code>time</code> command:

First, let's modify the code which sets up the new SPADS command handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addSpadsCommandHandler-handlers-replace-0 addSpadsCommandHandler]. This call is located in the plugin constructor. We edit it so that it becomes:
<syntaxhighlight lang="python">
[...]
# We declare our new command and the associated handler
addSpadsCommandHandler({time => \&hSpadsTime});
[...]
</syntaxhighlight>
We must modify the same way the code which removes this SPADS handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#removeSpadsCommandHandler-commands removeSpadsCommandHandler] in the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback:
<syntaxhighlight lang="python">
[...]
# We remove our new command handler
removeSpadsCommandHandler(['time']);
[...]
</syntaxhighlight>
Finally, we must replace the handler example <code>hMyCommand</code> by our own handler <code>hSpadsTime</code>. In order to answer to the user issuing the command, we can use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#answer-message answer], which will send an answer message to the user in the same way he sent the command (private message, battle lobby...).

Here is an implementation example for this basic command:
<syntaxhighlight lang="python">
# This is the handler for our new command
sub hSpadsTime {
my ($source,$user,$p_params,$checkOnly)=@_;

# time is a basic command, we have nothing to check in case of callvote
return 1 if($checkOnly);

my @time = localtime();
@time = map(sprintf("%02d",$_),@time);

answer("Current local time: $time[2]:$time[1]:$time[0]");
}
</syntaxhighlight>

Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/timeplugin.py this fully functional TimePlugin] plugin, and its associated [http://planetspads.free.fr/spads/plugins/tutorials/TimePlugin.conf configuration file], [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginCmd.conf command rights configuration file] and [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginHelp.dat command help file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module and the plugin help file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the 2 configuration files in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: <code>!plugin TimePlugin load</code>. And finally, we can try to say !time in a private message to SPADS or in the battle lobby, and SPADS should answer giving current local time. Our <code>!time</code> command help should also appear in <code>!help</code> and <code>!help time</code> outputs.

[[Category:SPADS]]

SPADS plugin development (Python)

2021-01-28T13:10:44Z

Bibim: /* Writing plugin code */

= Introduction =

SPADS is an autohost system coded in Perl, it supports both Perl and Python plugins. This tutorial deals with Python plugin development only (for Perl plugin development another tutorial is available [https://springrts.com/wiki/SPADS_plugin_development here]).

SPADS plugins are object-oriented modules. It is strongly recommended to already know Python basics before starting Python plugin development (a Python tutorial is available [https://docs.python.org/3/tutorial/ here]).

 
= Technical prerequisites =

Python (the Python interpreter and its libraries) must be installed on the system (versions 2.6+ or 3.2+ recommended). The type of installation (32-bit / 64-bit) must be consistent with the Perl version and the Spring engine used for SPADS.

Additionally, in order to allow communication between Perl code (SPADS core) and Python code (SPADS plugins), SPADS uses a Perl module named <code>Inline::Python</code> which must also be installed on the system. It is recommended to install the latest version for SPADS, refer to [https://springrts.com/wiki/SPADS_Inline::Python_installation_guide this guide] for installation.

 

= 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 [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] (the <code>.pm</code> files must be ignored for this tutorial, these are the Perl versions of the templates).

Our first plugin will be very basic, so we will use the simplest template: <code>mysimpleplugin.py</code>. Let's download [http://planetspads.free.fr/spads/plugins/templates/commented/mysimpleplugin.py 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 <code>HelloWorld</code>. We have to rename the downloaded template from <code>mysimpleplugin.py</code> to <code>helloworld.py</code>, and edit it to replace <code>MySimplePlugin</code> by <code>HelloWorld</code> 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 <code>spads.conf</code> configuration file and reload SPADS configuration).

We have to move our new plugin (<code>helloworld.py</code>) 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): <code>!plugin HelloWorld load</code>. SPADS should answer <code>Loaded plugin HelloWorld.</code>, 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-self-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 <code>onPrivateMsg</code> callback, which will answer <code>Hello World</code> to anyone saying <code>Hello</code> in a private message to SPADS:
<syntaxhighlight lang="python">
# This is the callback called each time SPADS receives a private message
# 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
def onPrivateMsg(self,userName,message):

# Here we "fix" strings received from Perl in case
# the Inline::Python module transmits them as byte strings
(userName,message)=spads.fix_string(userName,message)

# We check the message sent by the user is "Hello"
if message == 'Hello':

# We send our wonderful Hello World message
spads.sayPrivate(userName,'Hello World')

# We return 0 because we don't want to filter out private messages
# for other SPADS processing
return 0</syntaxhighlight>

All we have to do now is adding this callback declaration in our <code>helloworld.py</code> file located in SPADS plugins directory. We obtain [http://planetspads.free.fr/spads/plugins/tutorials/helloworld.py 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: <code>!plugin HelloWorld reload</code>. SPADS should answer <code>Reloaded plugin HelloWorld.</code>, which indicates the plugin has been reloaded successfully.

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

'''/!\ WORK IN PROGRESS /!\'''

 
= Configurable plugin tutorial (ForbiddenWords) =

In this section we are going to write our first configurable SPADS plugin (a configurable plugin has its own configuration file, named after the plugin name but with <code>.conf</code> extension). This plugin will monitor all messages said by players in the battle lobby, and will kick players who use swear words.

== Specifying our configuration parameters ==

The first step of writing a configurable plugin is to choose how we will configure it. In our example, we will use 2 configuration parameters: <code>words</code> will contain the list of forbidden words, and <code>immuneLevel</code> will contain the minimum autohost access level to be immune regarding these forbidden words checks.

We choose to make <code>words</code> a global setting (unmodifiable, not impacted by preset change), and <code>immuneLevel</code> a preset setting (modifiable, can be impacted by preset change). The <code>words</code> global setting will have no restriction (can be empty, can contain any character...), whereas the <code>immuneLevel</code> preset setting will only be allowed to be an integer or integer range.

== Preparing the template ==

Once we have a clear view of our configuration settings, we can start adapting the template for our needs. Since we are making a configurable plugin, this time we will download [http://planetspads.free.fr/spads/plugins/templates/commented/myconfigurableplugin.py the configurable plugin template] and its associated [http://planetspads.free.fr/spads/plugins/templates/commented/MyConfigurablePlugin.conf configuration file example].

First, let's take a look at the configuration file example. This is a just a basic configuration file containing one global setting example and one preset setting example. Let's modify this file to match the configuration we chose as follows (don't forget to rename the file from <code>MyConfigurablePlugin.conf</code> to <code>ForbiddenWords.conf</code> also):
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# This is our global setting (can't be changed without reloading the configuration)
words:ass;asshole;bastard;bitch;cunt;fuck;motherfucker;shit;whore

# We must define our preset setting in the default preset at least
[default]

# This is our preset setting, which can be changed with "!plugin ... set ..."
# or by loading a preset.
# "100" is the default value, and any integer between 0 and 140 is allowed
immuneLevel:100|0-140
|}
Then we must prepare the plugin template itself, by renaming it from <code>myconfigurableplugin.py</code> to <code>forbiddenwords.py</code> and editing it to replace <code>MyConfigurablePlugin</code> by <code>ForbiddenWords</code> in the source code. We must also adapt the template so that it uses the configuration settings we chose. This is done by modifying the <code>globalPluginParams</code> and <code>presetPluginParam</code> declarations as follows:
<syntaxhighlight lang="python">
# We define one global setting "words" and one preset setting "immuneLevel".
# "words" has no type associated (no restriction on allowed values)
# "immuneLevel" must be an integer or an integer range
# (check %paramTypes hash in SpadsConf.pm for a complete list of allowed
# setting types)
globalPluginParams = { 'words': [] }
presetPluginParams = { 'immuneLevel': ['integer','integerRange'] }
</syntaxhighlight>

== Writing plugin code ==

We want our plugin to react to messages said in the battle lobby. There is no dedicated callback for this event in [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html SPADS plugin API documentation], so we have to set up our own handler on the [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#SAIDBATTLE:server SAIDBATTLE lobby command]. To do so we have to call the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addLobbyCommandHandler-handlers-priority-caller addLobbyCommandHandler]. We will call this function at the end of our plugin constructor as follows, so that it will be set up directly when the plugin is loaded:
<syntaxhighlight lang="python">
[...]

# We set up a lobby command handler on SAIDBATTLE
spads.addLobbyCommandHandler({'SAIDBATTLE': hLobbySaidBattle})
</syntaxhighlight>
However, if SPADS is disconnected from the lobby due to network problems for example, all lobby handlers are automatically removed. So we must re-add them each time we connect to lobby server. This can be done using the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onLobbyConnected-self-lobbyInterface onLobbyConnected] event-based callback as follows:
<syntaxhighlight lang="python">
# This callback is called each time we (re)connect to the lobby server
def onLobbyConnected(self,lobbyInterface):

# When we are disconnected from the lobby server, all lobby command
# handlers are automatically removed, so we (re)set up our command
# handler here.
spads.addLobbyCommandHandler({'SAIDBATTLE': hLobbySaidBattle})
</syntaxhighlight>
Also, it is a good practice to remove any handler we have added when the plugin is unloaded. To do so we must implement the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback as follows:
<syntaxhighlight lang="python">
# This callback is called when the plugin is unloaded
def onUnload(self,reason):

# We remove our lobby command handler when the plugin is unloaded
spads.removeLobbyCommandHandler(['SAIDBATTLE'])
</syntaxhighlight>
Finally, we have to implement our <code>SAIDBATTLE</code> handler <code>hLobbySaidBattle</code>. In this handler we need to perform following operations:
* skip processing if the user is the autohost itself: we need to access SPADS configuration to compare the user name with the [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:lobbyLogin lobbyLogin] setting value. So we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getSpadsConf getSpadsConf].
* perform processing according to our configuration (<code>words</code> and <code>immuneLevel</code> settings): we need to access our plugin configuration, so we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getPluginConf-pluginName-caller getPluginConf].
* retrieve the autohost access level of the user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getUserAccessLevel-user getUserAccessLevel]
* send a message to the battle lobby when we kick someone: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#sayBattle-message sayBattle].
* send a [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#KICKFROMBATTLE:client KICKFROMBATTLE] lobby command to kick a user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#queueLobbyCommand-lobbyCommand queueLobbyCommand].

Here is a commented implementation example of this <code>hLobbySaidBattle</code> handler, which will kick any non-privileged user saying a forbidden word in the battle lobby:
<syntaxhighlight lang="python">
# This is the handler we set up on SAIDBATTLE lobby command.
# It is called each time a player says something in the battle lobby.
# command is the lobby command name (SAIDBATTLE)
# user is the name of the user who said something in the battle lobby
# message is the message said in the battle lobby
def hLobbySaidBattle(command,user,message):

# First we "fix" strings received from Perl in case
# the Inline::Python module transmits them as byte strings
(user,message)=spads.fix_string(user,message)

# Here we check it's not a message from SPADS (so we don't kick ourself)
spadsConf = spads.getSpadsConf()
if user == spadsConf['lobbyLogin']:
return

# Then we check the user isn't a privileged user
# (autohost access level >= immuneLevel)
pluginConf = spads.getPluginConf()
if int(spads.getUserAccessLevel(user)) >= int(pluginConf['immuneLevel']):
return

# We put the forbidden words in a list
forbiddenWords = pluginConf['words'].split(';')

# We test each forbidden word
for forbiddenWord in forbiddenWords:

# If the message contains the forbidden word (case insensitive)
if re.search(r'\b' + re.escape(forbiddenWord) + r'\b',message,re.IGNORECASE):

# Then we kick the user from the battle lobby
spads.sayBattle("Kicking %s from battle (watch your language!)" % user)
spads.queueLobbyCommand(["KICKFROMBATTLE",user])

# We quit the foreach loop (no need to test other forbidden word)
break
</syntaxhighlight>

As we are using regular expressions in our plugin code, we must not forget to import the <code>re</code> Python module at the start of our plugin:
<syntaxhighlight lang="python">
# Import the regular expression module to check for forbidden words
import re
</syntaxhighlight>
Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/forbiddenwords.py this fully functional ForbiddenWords] plugin and [http://planetspads.free.fr/spads/plugins/tutorials/ForbiddenWords.conf its associated configuration file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the associated configuration file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: <code>!plugin ForbiddenWords load</code>. And finally, as an unprivileged user we can try to say some forbidden words in the battle lobby and we should get kicked by the plugin.

 

= New-command plugin tutorial (TimePlugin) =

In this section we are going to write a plugin which implements a new command for SPADS. Such plugins are configurable plugins like the one we wrote just before, with 2 additional files to configure the new commands. This plugin will give current time when someone types <code>!time</code>.

== Preparing the template ==

This time we need to download 4 files to prepare our plugin: [http://planetspads.free.fr/spads/plugins/templates/commented/mynewcommandplugin.py the new-command plugin template], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPlugin.conf the associated configuration file example], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginHelp.dat the help file example] and [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginCmd.conf the commands rights configuration file example].

As usual, we rename these files to match our plugin name: <code>MyNewCommandPlugin</code> --> <code>TimePlugin</code>. Then we edit the plugin template <code>timeplugin.py</code> and replace <code>MyNewCommandPlugin</code> by <code>TimePlugin</code> in the source code, and we do the same for the plugin configuration template <code>TimePlugin.conf</code>, so that the <code>commandsFile</code> and <code>helpFile</code> settings are consistent with the files we just renamed.

Then we can edit our command rights requirements configuration file: <code>TimePluginCmd.conf</code>. This file uses the same syntax as the standard SPADS <code>commands.conf</code> file. The template provides a default command <code>myCommand</code> with no requirement. We will just rename this command to <code>time</code>:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# Anyone can call our command from anywhere
[time]
::|0:
|}
Now we need to write the help information for our new command. This is done in the file <code>TimePluginHelp.dat</code>. This file uses the same syntax as the standard SPADS <code>help.dat</code> file, and the template provides a help example for a command <code>myCommand</code> as a syntax reminder. After each command declaration, the first line is the command syntax description, and the other lines are optional usage examples. Let's replace this help example with our own help information for our basic <code>!time</code> command:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
[time]
<nowiki>!</nowiki>time - This command just prints current time
|}
== Writing plugin code ==

The new-command plugin template that we used to initialize our plugin already defines a new command named <code>myCommand</code>, so all we have to do is to edit our plugin file ( <code>timeplugin.py</code> ) and replace this command by our own <code>time</code> command:

First, let's modify the code which sets up the new SPADS command handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addSpadsCommandHandler-handlers-replace-0 addSpadsCommandHandler]. This call is located in the plugin constructor. We edit it so that it becomes:
<syntaxhighlight lang="python">
[...]
# We declare our new command and the associated handler
addSpadsCommandHandler({time => \&hSpadsTime});
[...]
</syntaxhighlight>
We must modify the same way the code which removes this SPADS handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#removeSpadsCommandHandler-commands removeSpadsCommandHandler] in the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback:
<syntaxhighlight lang="python">
[...]
# We remove our new command handler
removeSpadsCommandHandler(['time']);
[...]
</syntaxhighlight>
Finally, we must replace the handler example <code>hMyCommand</code> by our own handler <code>hSpadsTime</code>. In order to answer to the user issuing the command, we can use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#answer-message answer], which will send an answer message to the user in the same way he sent the command (private message, battle lobby...).

Here is an implementation example for this basic command:
<syntaxhighlight lang="python">
# This is the handler for our new command
sub hSpadsTime {
my ($source,$user,$p_params,$checkOnly)=@_;

# time is a basic command, we have nothing to check in case of callvote
return 1 if($checkOnly);

my @time = localtime();
@time = map(sprintf("%02d",$_),@time);

answer("Current local time: $time[2]:$time[1]:$time[0]");
}
</syntaxhighlight>

Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/timeplugin.py this fully functional TimePlugin] plugin, and its associated [http://planetspads.free.fr/spads/plugins/tutorials/TimePlugin.conf configuration file], [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginCmd.conf command rights configuration file] and [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginHelp.dat command help file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module and the plugin help file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the 2 configuration files in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: <code>!plugin TimePlugin load</code>. And finally, we can try to say !time in a private message to SPADS or in the battle lobby, and SPADS should answer giving current local time. Our <code>!time</code> command help should also appear in <code>!help</code> and <code>!help time</code> outputs.

[[Category:SPADS]]

SPADS plugin development (Python)

2021-01-28T12:35:45Z

Bibim: /* Preparing the template */

= Introduction =

SPADS is an autohost system coded in Perl, it supports both Perl and Python plugins. This tutorial deals with Python plugin development only (for Perl plugin development another tutorial is available [https://springrts.com/wiki/SPADS_plugin_development here]).

SPADS plugins are object-oriented modules. It is strongly recommended to already know Python basics before starting Python plugin development (a Python tutorial is available [https://docs.python.org/3/tutorial/ here]).

 
= Technical prerequisites =

Python (the Python interpreter and its libraries) must be installed on the system (versions 2.6+ or 3.2+ recommended). The type of installation (32-bit / 64-bit) must be consistent with the Perl version and the Spring engine used for SPADS.

Additionally, in order to allow communication between Perl code (SPADS core) and Python code (SPADS plugins), SPADS uses a Perl module named <code>Inline::Python</code> which must also be installed on the system. It is recommended to install the latest version for SPADS, refer to [https://springrts.com/wiki/SPADS_Inline::Python_installation_guide this guide] for installation.

 

= 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 [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] (the <code>.pm</code> files must be ignored for this tutorial, these are the Perl versions of the templates).

Our first plugin will be very basic, so we will use the simplest template: <code>mysimpleplugin.py</code>. Let's download [http://planetspads.free.fr/spads/plugins/templates/commented/mysimpleplugin.py 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 <code>HelloWorld</code>. We have to rename the downloaded template from <code>mysimpleplugin.py</code> to <code>helloworld.py</code>, and edit it to replace <code>MySimplePlugin</code> by <code>HelloWorld</code> 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 <code>spads.conf</code> configuration file and reload SPADS configuration).

We have to move our new plugin (<code>helloworld.py</code>) 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): <code>!plugin HelloWorld load</code>. SPADS should answer <code>Loaded plugin HelloWorld.</code>, 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-self-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 <code>onPrivateMsg</code> callback, which will answer <code>Hello World</code> to anyone saying <code>Hello</code> in a private message to SPADS:
<syntaxhighlight lang="python">
# This is the callback called each time SPADS receives a private message
# 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
def onPrivateMsg(self,userName,message):

# Here we "fix" strings received from Perl in case
# the Inline::Python module transmits them as byte strings
(userName,message)=spads.fix_string(userName,message)

# We check the message sent by the user is "Hello"
if message == 'Hello':

# We send our wonderful Hello World message
spads.sayPrivate(userName,'Hello World')

# We return 0 because we don't want to filter out private messages
# for other SPADS processing
return 0</syntaxhighlight>

All we have to do now is adding this callback declaration in our <code>helloworld.py</code> file located in SPADS plugins directory. We obtain [http://planetspads.free.fr/spads/plugins/tutorials/helloworld.py 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: <code>!plugin HelloWorld reload</code>. SPADS should answer <code>Reloaded plugin HelloWorld.</code>, which indicates the plugin has been reloaded successfully.

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

'''/!\ WORK IN PROGRESS /!\'''

 
= Configurable plugin tutorial (ForbiddenWords) =

In this section we are going to write our first configurable SPADS plugin (a configurable plugin has its own configuration file, named after the plugin name but with <code>.conf</code> extension). This plugin will monitor all messages said by players in the battle lobby, and will kick players who use swear words.

== Specifying our configuration parameters ==

The first step of writing a configurable plugin is to choose how we will configure it. In our example, we will use 2 configuration parameters: <code>words</code> will contain the list of forbidden words, and <code>immuneLevel</code> will contain the minimum autohost access level to be immune regarding these forbidden words checks.

We choose to make <code>words</code> a global setting (unmodifiable, not impacted by preset change), and <code>immuneLevel</code> a preset setting (modifiable, can be impacted by preset change). The <code>words</code> global setting will have no restriction (can be empty, can contain any character...), whereas the <code>immuneLevel</code> preset setting will only be allowed to be an integer or integer range.

== Preparing the template ==

Once we have a clear view of our configuration settings, we can start adapting the template for our needs. Since we are making a configurable plugin, this time we will download [http://planetspads.free.fr/spads/plugins/templates/commented/myconfigurableplugin.py the configurable plugin template] and its associated [http://planetspads.free.fr/spads/plugins/templates/commented/MyConfigurablePlugin.conf configuration file example].

First, let's take a look at the configuration file example. This is a just a basic configuration file containing one global setting example and one preset setting example. Let's modify this file to match the configuration we chose as follows (don't forget to rename the file from <code>MyConfigurablePlugin.conf</code> to <code>ForbiddenWords.conf</code> also):
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# This is our global setting (can't be changed without reloading the configuration)
words:ass;asshole;bastard;bitch;cunt;fuck;motherfucker;shit;whore

# We must define our preset setting in the default preset at least
[default]

# This is our preset setting, which can be changed with "!plugin ... set ..."
# or by loading a preset.
# "100" is the default value, and any integer between 0 and 140 is allowed
immuneLevel:100|0-140
|}
Then we must prepare the plugin template itself, by renaming it from <code>myconfigurableplugin.py</code> to <code>forbiddenwords.py</code> and editing it to replace <code>MyConfigurablePlugin</code> by <code>ForbiddenWords</code> in the source code. We must also adapt the template so that it uses the configuration settings we chose. This is done by modifying the <code>globalPluginParams</code> and <code>presetPluginParam</code> declarations as follows:
<syntaxhighlight lang="python">
# We define one global setting "words" and one preset setting "immuneLevel".
# "words" has no type associated (no restriction on allowed values)
# "immuneLevel" must be an integer or an integer range
# (check %paramTypes hash in SpadsConf.pm for a complete list of allowed
# setting types)
globalPluginParams = { 'words': [] }
presetPluginParams = { 'immuneLevel': ['integer','integerRange'] }
</syntaxhighlight>

== Writing plugin code ==

We want our plugin to react to messages said in the battle lobby. There is no dedicated callback for this event in [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html SPADS plugin API documentation], so we have to set up our own handler on the [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#SAIDBATTLE:server SAIDBATTLE lobby command]. To do so we have to call the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addLobbyCommandHandler-handlers-priority-caller addLobbyCommandHandler]. We will call this function at the end of our plugin constructor as follows, so that it will be set up directly when the plugin is loaded:
<syntaxhighlight lang="python">
[...]

# We set up a lobby command handler on SAIDBATTLE
addLobbyCommandHandler({SAIDBATTLE => \&hLobbySaidBattle});

# We return the instantiated plugin
return $self;

}
</syntaxhighlight>
However, if SPADS is disconnected from the lobby due to network problems for example, all lobby handlers are automatically removed. So we must re-add them each time we connect to lobby server. This can be done using the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onLobbyConnected-self-lobbyInterface onLobbyConnected] event-based callback as follows:
<syntaxhighlight lang="python">
# This callback is called each time we (re)connect to the lobby server
sub onLobbyConnected {

# When we are disconnected from the lobby server, all lobby command
# handlers are automatically removed, so we (re)set up our command
# handler here.
addLobbyCommandHandler({SAIDBATTLE => \&hLobbySaidBattle});

}
</syntaxhighlight>
Also, it is a good practice to remove any handler we have added when the plugin is unloaded. To do so we must implement the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback as follows:
<syntaxhighlight lang="python">
# This callback is called when the plugin is unloaded
sub onUnload {

# We remove our lobby command handler when the plugin is unloaded
removeLobbyCommandHandler(['SAIDBATTLE']);

}
</syntaxhighlight>
Finally, we have to implement our <code>SAIDBATTLE</code> handler <code>hLobbySaidBattle</code>. In this handler we need to perform following operations:
* skip processing if the user is the autohost itself: we need to access SPADS configuration to compare the user name with the [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:lobbyLogin lobbyLogin] setting value. So we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getSpadsConf getSpadsConf].
* perform processing according to our configuration (<code>words</code> and <code>immuneLevel</code> settings): we need to access our plugin configuration, so we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getPluginConf-pluginName-caller getPluginConf].
* retrieve the autohost access level of the user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getUserAccessLevel-user getUserAccessLevel]
* send a message to the battle lobby when we kick someone: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#sayBattle-message sayBattle].
* send a [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#KICKFROMBATTLE:client KICKFROMBATTLE] lobby command to kick a user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#queueLobbyCommand-lobbyCommand queueLobbyCommand].

Here is a commented implementation example of this <code>hLobbySaidBattle</code> handler, which will kick any non-privileged user saying a forbidden word in the battle lobby:
<syntaxhighlight lang="python">
# This is the handler we set up on SAIDBATTLE lobby command.
# It is called each time a player says something in the battle lobby.
sub hLobbySaidBattle {

# $command is the lobby command name (SAIDBATTLE)
# $user is the name of the user who said something in the battle lobby
# $message is the message said in the battle lobby
my ($command,$user,$message)=@_;

# First we check it's not a message from SPADS (so we don't kick ourself)
my $p_spadsConf=getSpadsConf();
return if($user eq $p_spadsConf->{lobbyLogin});

# Then we check the user isn't a privileged user
# (autohost access level >= immuneLevel)
my $p_conf=getPluginConf();
return if(getUserAccessLevel($user) >= $p_conf->{immuneLevel});

# We put the forbidden words in a array
my @forbiddenWords=split(/;/,$p_conf->{words});

# We test each forbidden word
foreach my $forbiddenWord (@forbiddenWords) {

# If the message contains the forbidden word (case insensitive)
if($message =~ /\b$forbiddenWord\b/i) {

# Then we kick the user from the battle lobby
sayBattle("Kicking $user from battle (watch your language!)");
queueLobbyCommand(["KICKFROMBATTLE",$user]);

# We quit the foreach loop (no need to test other forbidden word)
last;

}

}

}
</syntaxhighlight>

As we are using regular expressions in our plugin code, we must import the <code>re</code> Python module at the start of our plugin code:
<syntaxhighlight lang="python">
# Import the regular expression module to check for forbidden words
import re
</syntaxhighlight>
Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/forbiddenwords.py this fully functional ForbiddenWords] plugin and [http://planetspads.free.fr/spads/plugins/tutorials/ForbiddenWords.conf its associated configuration file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the associated configuration file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: <code>!plugin ForbiddenWords load</code>. And finally, as an unprivileged user we can try to say some forbidden words in the battle lobby and we should get kicked by the plugin.

 

= New-command plugin tutorial (TimePlugin) =

In this section we are going to write a plugin which implements a new command for SPADS. Such plugins are configurable plugins like the one we wrote just before, with 2 additional files to configure the new commands. This plugin will give current time when someone types <code>!time</code>.

== Preparing the template ==

This time we need to download 4 files to prepare our plugin: [http://planetspads.free.fr/spads/plugins/templates/commented/mynewcommandplugin.py the new-command plugin template], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPlugin.conf the associated configuration file example], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginHelp.dat the help file example] and [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginCmd.conf the commands rights configuration file example].

As usual, we rename these files to match our plugin name: <code>MyNewCommandPlugin</code> --> <code>TimePlugin</code>. Then we edit the plugin template <code>timeplugin.py</code> and replace <code>MyNewCommandPlugin</code> by <code>TimePlugin</code> in the source code, and we do the same for the plugin configuration template <code>TimePlugin.conf</code>, so that the <code>commandsFile</code> and <code>helpFile</code> settings are consistent with the files we just renamed.

Then we can edit our command rights requirements configuration file: <code>TimePluginCmd.conf</code>. This file uses the same syntax as the standard SPADS <code>commands.conf</code> file. The template provides a default command <code>myCommand</code> with no requirement. We will just rename this command to <code>time</code>:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# Anyone can call our command from anywhere
[time]
::|0:
|}
Now we need to write the help information for our new command. This is done in the file <code>TimePluginHelp.dat</code>. This file uses the same syntax as the standard SPADS <code>help.dat</code> file, and the template provides a help example for a command <code>myCommand</code> as a syntax reminder. After each command declaration, the first line is the command syntax description, and the other lines are optional usage examples. Let's replace this help example with our own help information for our basic <code>!time</code> command:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
[time]
<nowiki>!</nowiki>time - This command just prints current time
|}
== Writing plugin code ==

The new-command plugin template that we used to initialize our plugin already defines a new command named <code>myCommand</code>, so all we have to do is to edit our plugin file ( <code>timeplugin.py</code> ) and replace this command by our own <code>time</code> command:

First, let's modify the code which sets up the new SPADS command handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addSpadsCommandHandler-handlers-replace-0 addSpadsCommandHandler]. This call is located in the plugin constructor. We edit it so that it becomes:
<syntaxhighlight lang="python">
[...]
# We declare our new command and the associated handler
addSpadsCommandHandler({time => \&hSpadsTime});
[...]
</syntaxhighlight>
We must modify the same way the code which removes this SPADS handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#removeSpadsCommandHandler-commands removeSpadsCommandHandler] in the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback:
<syntaxhighlight lang="python">
[...]
# We remove our new command handler
removeSpadsCommandHandler(['time']);
[...]
</syntaxhighlight>
Finally, we must replace the handler example <code>hMyCommand</code> by our own handler <code>hSpadsTime</code>. In order to answer to the user issuing the command, we can use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#answer-message answer], which will send an answer message to the user in the same way he sent the command (private message, battle lobby...).

Here is an implementation example for this basic command:
<syntaxhighlight lang="python">
# This is the handler for our new command
sub hSpadsTime {
my ($source,$user,$p_params,$checkOnly)=@_;

# time is a basic command, we have nothing to check in case of callvote
return 1 if($checkOnly);

my @time = localtime();
@time = map(sprintf("%02d",$_),@time);

answer("Current local time: $time[2]:$time[1]:$time[0]");
}
</syntaxhighlight>

Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/timeplugin.py this fully functional TimePlugin] plugin, and its associated [http://planetspads.free.fr/spads/plugins/tutorials/TimePlugin.conf configuration file], [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginCmd.conf command rights configuration file] and [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginHelp.dat command help file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module and the plugin help file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the 2 configuration files in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: <code>!plugin TimePlugin load</code>. And finally, we can try to say !time in a private message to SPADS or in the battle lobby, and SPADS should answer giving current local time. Our <code>!time</code> command help should also appear in <code>!help</code> and <code>!help time</code> outputs.

[[Category:SPADS]]

SPADS plugin development (Python)

2021-01-28T11:33:09Z

Bibim: /* Writing plugin code */

= Introduction =

SPADS is an autohost system coded in Perl, it supports both Perl and Python plugins. This tutorial deals with Python plugin development only (for Perl plugin development another tutorial is available [https://springrts.com/wiki/SPADS_plugin_development here]).

SPADS plugins are object-oriented modules. It is strongly recommended to already know Python basics before starting Python plugin development (a Python tutorial is available [https://docs.python.org/3/tutorial/ here]).

 
= Technical prerequisites =

Python (the Python interpreter and its libraries) must be installed on the system (versions 2.6+ or 3.2+ recommended). The type of installation (32-bit / 64-bit) must be consistent with the Perl version and the Spring engine used for SPADS.

Additionally, in order to allow communication between Perl code (SPADS core) and Python code (SPADS plugins), SPADS uses a Perl module named <code>Inline::Python</code> which must also be installed on the system. It is recommended to install the latest version for SPADS, refer to [https://springrts.com/wiki/SPADS_Inline::Python_installation_guide this guide] for installation.

 

= 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 [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] (the <code>.pm</code> files must be ignored for this tutorial, these are the Perl versions of the templates).

Our first plugin will be very basic, so we will use the simplest template: <code>mysimpleplugin.py</code>. Let's download [http://planetspads.free.fr/spads/plugins/templates/commented/mysimpleplugin.py 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 <code>HelloWorld</code>. We have to rename the downloaded template from <code>mysimpleplugin.py</code> to <code>helloworld.py</code>, and edit it to replace <code>MySimplePlugin</code> by <code>HelloWorld</code> 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 <code>spads.conf</code> configuration file and reload SPADS configuration).

We have to move our new plugin (<code>helloworld.py</code>) 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): <code>!plugin HelloWorld load</code>. SPADS should answer <code>Loaded plugin HelloWorld.</code>, 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-self-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 <code>onPrivateMsg</code> callback, which will answer <code>Hello World</code> to anyone saying <code>Hello</code> in a private message to SPADS:
<syntaxhighlight lang="python">
# This is the callback called each time SPADS receives a private message
# 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
def onPrivateMsg(self,userName,message):

# Here we "fix" strings received from Perl in case
# the Inline::Python module transmits them as byte strings
(userName,message)=spads.fix_string(userName,message)

# We check the message sent by the user is "Hello"
if message == 'Hello':

# We send our wonderful Hello World message
spads.sayPrivate(userName,'Hello World')

# We return 0 because we don't want to filter out private messages
# for other SPADS processing
return 0</syntaxhighlight>

All we have to do now is adding this callback declaration in our <code>helloworld.py</code> file located in SPADS plugins directory. We obtain [http://planetspads.free.fr/spads/plugins/tutorials/helloworld.py 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: <code>!plugin HelloWorld reload</code>. SPADS should answer <code>Reloaded plugin HelloWorld.</code>, which indicates the plugin has been reloaded successfully.

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

'''/!\ WORK IN PROGRESS /!\'''

 
= Configurable plugin tutorial (ForbiddenWords) =

In this section we are going to write our first configurable SPADS plugin (a configurable plugin has its own configuration file, named after the plugin name but with <code>.conf</code> extension). This plugin will monitor all messages said by players in the battle lobby, and will kick players who use swear words.

== Specifying our configuration parameters ==

The first step of writing a configurable plugin is to choose how we will configure it. In our example, we will use 2 configuration parameters: <code>words</code> will contain the list of forbidden words, and <code>immuneLevel</code> will contain the minimum autohost access level to be immune regarding these forbidden words checks.

We choose to make <code>words</code> a global setting (unmodifiable, not impacted by preset change), and <code>immuneLevel</code> a preset setting (modifiable, can be impacted by preset change). The <code>words</code> global setting will have no restriction (can be empty, can contain any character...), whereas the <code>immuneLevel</code> preset setting will only be allowed to be an integer or integer range.

== Preparing the template ==

Once we have a clear view of our configuration settings, we can start adapting the template for our needs. Since we are making a configurable plugin, this time we will download [http://planetspads.free.fr/spads/plugins/templates/commented/myconfigurableplugin.py the configurable plugin template] and its associated [http://planetspads.free.fr/spads/plugins/templates/commented/MyConfigurablePlugin.conf configuration file example].

First, let's take a look at the configuration file example. This is a just a basic configuration file containing one global setting example and one preset setting example. Let's modify this file to match the configuration we chose as follows (don't forget to rename the file from <code>MyConfigurablePlugin.conf</code> to <code>ForbiddenWords.conf</code> also):
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# This is our global setting (can't be changed without reloading the configuration)
words:ass;asshole;bastard;bitch;cunt;fuck;motherfucker;shit;whore

# We must define our preset setting in the default preset at least
[default]

# This is our preset setting, which can be changed with "!plugin ... set ..."
# or by loading a preset.
# "100" is the default value, and any integer between 0 and 140 is allowed
immuneLevel:100|0-140
|}
Then we must prepare the plugin template itself, by renaming it from <code>myconfigurableplugin.py</code> to <code>forbiddenwords.py</code> and editing it to replace <code>MyConfigurablePlugin</code> by <code>ForbiddenWords</code> in the source code. We must also adapt the template so that it uses the configuration settings we chose. This is done by modifying the <code>globalPluginParams</code> and <code>presetPluginParam</code> declarations as follows:
<syntaxhighlight lang="python">
# We define one global setting "words" and one preset setting "immuneLevel".
# "words" has no type associated (no restriction on allowed values)
# "immuneLevel" must be an integer or an integer range
# (check %paramTypes hash in SpadsConf.pm for a complete list of allowed
# setting types)
globalPluginParams = { 'words': [] }
presetPluginParams = { 'immuneLevel': ['integer','integerRange'] }
</syntaxhighlight>

== Writing plugin code ==

We want our plugin to react to messages said in the battle lobby. There is no dedicated callback for this event in [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html SPADS plugin API documentation], so we have to set up our own handler on the [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#SAIDBATTLE:server SAIDBATTLE lobby command]. To do so we have to call the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addLobbyCommandHandler-handlers-priority-caller addLobbyCommandHandler]. We will call this function at the end of our plugin constructor as follows, so that it will be set up directly when the plugin is loaded:
<syntaxhighlight lang="python">
[...]

# We set up a lobby command handler on SAIDBATTLE
addLobbyCommandHandler({SAIDBATTLE => \&hLobbySaidBattle});

# We return the instantiated plugin
return $self;

}
</syntaxhighlight>
However, if SPADS is disconnected from the lobby due to network problems for example, all lobby handlers are automatically removed. So we must re-add them each time we connect to lobby server. This can be done using the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onLobbyConnected-self-lobbyInterface onLobbyConnected] event-based callback as follows:
<syntaxhighlight lang="python">
# This callback is called each time we (re)connect to the lobby server
sub onLobbyConnected {

# When we are disconnected from the lobby server, all lobby command
# handlers are automatically removed, so we (re)set up our command
# handler here.
addLobbyCommandHandler({SAIDBATTLE => \&hLobbySaidBattle});

}
</syntaxhighlight>
Also, it is a good practice to remove any handler we have added when the plugin is unloaded. To do so we must implement the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback as follows:
<syntaxhighlight lang="python">
# This callback is called when the plugin is unloaded
sub onUnload {

# We remove our lobby command handler when the plugin is unloaded
removeLobbyCommandHandler(['SAIDBATTLE']);

}
</syntaxhighlight>
Finally, we have to implement our <code>SAIDBATTLE</code> handler <code>hLobbySaidBattle</code>. In this handler we need to perform following operations:
* skip processing if the user is the autohost itself: we need to access SPADS configuration to compare the user name with the [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:lobbyLogin lobbyLogin] setting value. So we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getSpadsConf getSpadsConf].
* perform processing according to our configuration (<code>words</code> and <code>immuneLevel</code> settings): we need to access our plugin configuration, so we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getPluginConf-pluginName-caller getPluginConf].
* retrieve the autohost access level of the user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getUserAccessLevel-user getUserAccessLevel]
* send a message to the battle lobby when we kick someone: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#sayBattle-message sayBattle].
* send a [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#KICKFROMBATTLE:client KICKFROMBATTLE] lobby command to kick a user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#queueLobbyCommand-lobbyCommand queueLobbyCommand].

Here is a commented implementation example of this <code>hLobbySaidBattle</code> handler, which will kick any non-privileged user saying a forbidden word in the battle lobby:
<syntaxhighlight lang="python">
# This is the handler we set up on SAIDBATTLE lobby command.
# It is called each time a player says something in the battle lobby.
sub hLobbySaidBattle {

# $command is the lobby command name (SAIDBATTLE)
# $user is the name of the user who said something in the battle lobby
# $message is the message said in the battle lobby
my ($command,$user,$message)=@_;

# First we check it's not a message from SPADS (so we don't kick ourself)
my $p_spadsConf=getSpadsConf();
return if($user eq $p_spadsConf->{lobbyLogin});

# Then we check the user isn't a privileged user
# (autohost access level >= immuneLevel)
my $p_conf=getPluginConf();
return if(getUserAccessLevel($user) >= $p_conf->{immuneLevel});

# We put the forbidden words in a array
my @forbiddenWords=split(/;/,$p_conf->{words});

# We test each forbidden word
foreach my $forbiddenWord (@forbiddenWords) {

# If the message contains the forbidden word (case insensitive)
if($message =~ /\b$forbiddenWord\b/i) {

# Then we kick the user from the battle lobby
sayBattle("Kicking $user from battle (watch your language!)");
queueLobbyCommand(["KICKFROMBATTLE",$user]);

# We quit the foreach loop (no need to test other forbidden word)
last;

}

}

}
</syntaxhighlight>

As we are using regular expressions in our plugin code, we must import the <code>re</code> Python module at the start of our plugin code:
<syntaxhighlight lang="python">
# Import the regular expression module to check for forbidden words
import re
</syntaxhighlight>
Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/forbiddenwords.py this fully functional ForbiddenWords] plugin and [http://planetspads.free.fr/spads/plugins/tutorials/ForbiddenWords.conf its associated configuration file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the associated configuration file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: <code>!plugin ForbiddenWords load</code>. And finally, as an unprivileged user we can try to say some forbidden words in the battle lobby and we should get kicked by the plugin.

 

= New-command plugin tutorial (TimePlugin) =

In this section we are going to write a plugin which implements a new command for SPADS. Such plugins are configurable plugins like the one we wrote just before, with 2 additional files to configure the new commands. This plugin will give current time when someone types <code>!time</code>.

== Preparing the template ==

This time we need to download 4 files to prepare our plugin: [http://planetspads.free.fr/spads/plugins/templates/commented/mynewcommandplugin.py the new-command plugin template], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPlugin.conf the associated configuration file example], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginHelp.dat the help file example] and [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginCmd.conf the commands rights configuration file example].

As usual, we rename these files to match our plugin name: <code>MyNewCommandPlugin</code> --> <code>TimePlugin</code>. Then we edit the plugin template <code>timeplugin.py</code> and replace <code>MyNewCommandPlugin</code> by <code>TimePlugin</code> in the source code, and we do the same for the plugin configuration template <code>TimePlugin.conf</code>, so that the <code>commandsFile</code> and <code>helpFile</code> settings are consistent with the files we just renamed.

Then we can edit our command rights requirements configuration file: <code>TimePluginCmd.conf</code>. This file uses the same syntax as the standard SPADS <code>commands.conf</code> file. The template provides a default command <code>myCommand</code> with no requirement. We will just rename this command to <code>time</code>:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# Anyone can call our command from anywhere
[time]
::|0:
|}
Now we need to write the help information for our new command. This is done in the file <code>TimePluginHelp.dat</code>. This file uses the same syntax as the standard SPADS <code>help.dat</code> file, and the template provides a help example for a command <code>myCommand</code> as a syntax reminder. After each command declaration, the first line is the command syntax description, and the other lines are optional usage examples. Let's replace this help example with our own help information for our basic <code>!time</code> command:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
[time]
<nowiki>!</nowiki>time - This command just prints current time
|}
== Writing plugin code ==

The new-command plugin template that we used to initialize our plugin already defines a new command named <code>myCommand</code>, so all we have to do is to edit our plugin file ( <code>timeplugin.py</code> ) and replace this command by our own <code>time</code> command:

First, let's modify the code which sets up the new SPADS command handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addSpadsCommandHandler-handlers-replace-0 addSpadsCommandHandler]. This call is located in the plugin constructor. We edit it so that it becomes:
<syntaxhighlight lang="python">
[...]
# We declare our new command and the associated handler
addSpadsCommandHandler({time => \&hSpadsTime});
[...]
</syntaxhighlight>
We must modify the same way the code which removes this SPADS handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#removeSpadsCommandHandler-commands removeSpadsCommandHandler] in the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback:
<syntaxhighlight lang="python">
[...]
# We remove our new command handler
removeSpadsCommandHandler(['time']);
[...]
</syntaxhighlight>
Finally, we must replace the handler example <code>hMyCommand</code> by our own handler <code>hSpadsTime</code>. In order to answer to the user issuing the command, we can use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#answer-message answer], which will send an answer message to the user in the same way he sent the command (private message, battle lobby...).

Here is an implementation example for this basic command:
<syntaxhighlight lang="python">
# This is the handler for our new command
sub hSpadsTime {
my ($source,$user,$p_params,$checkOnly)=@_;

# time is a basic command, we have nothing to check in case of callvote
return 1 if($checkOnly);

my @time = localtime();
@time = map(sprintf("%02d",$_),@time);

answer("Current local time: $time[2]:$time[1]:$time[0]");
}
</syntaxhighlight>

Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/timeplugin.py this fully functional TimePlugin] plugin, and its associated [http://planetspads.free.fr/spads/plugins/tutorials/TimePlugin.conf configuration file], [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginCmd.conf command rights configuration file] and [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginHelp.dat command help file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module and the plugin help file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the 2 configuration files in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: <code>!plugin TimePlugin load</code>. And finally, we can try to say !time in a private message to SPADS or in the battle lobby, and SPADS should answer giving current local time. Our <code>!time</code> command help should also appear in <code>!help</code> and <code>!help time</code> outputs.

[[Category:SPADS]]

SPADS plugin development (Python)

2021-01-28T11:14:08Z

Bibim: /* Preparing the template */

= Introduction =

SPADS is an autohost system coded in Perl, it supports both Perl and Python plugins. This tutorial deals with Python plugin development only (for Perl plugin development another tutorial is available [https://springrts.com/wiki/SPADS_plugin_development here]).

SPADS plugins are object-oriented modules. It is strongly recommended to already know Python basics before starting Python plugin development (a Python tutorial is available [https://docs.python.org/3/tutorial/ here]).

 
= Technical prerequisites =

Python (the Python interpreter and its libraries) must be installed on the system (versions 2.6+ or 3.2+ recommended). The type of installation (32-bit / 64-bit) must be consistent with the Perl version and the Spring engine used for SPADS.

Additionally, in order to allow communication between Perl code (SPADS core) and Python code (SPADS plugins), SPADS uses a Perl module named <code>Inline::Python</code> which must also be installed on the system. It is recommended to install the latest version for SPADS, refer to [https://springrts.com/wiki/SPADS_Inline::Python_installation_guide this guide] for installation.

 

= 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 [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] (the <code>.pm</code> files must be ignored for this tutorial, these are the Perl versions of the templates).

Our first plugin will be very basic, so we will use the simplest template: <code>mysimpleplugin.py</code>. Let's download [http://planetspads.free.fr/spads/plugins/templates/commented/mysimpleplugin.py 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 <code>HelloWorld</code>. We have to rename the downloaded template from <code>mysimpleplugin.py</code> to <code>helloworld.py</code>, and edit it to replace <code>MySimplePlugin</code> by <code>HelloWorld</code> 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 <code>spads.conf</code> configuration file and reload SPADS configuration).

We have to move our new plugin (<code>helloworld.py</code>) 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): <code>!plugin HelloWorld load</code>. SPADS should answer <code>Loaded plugin HelloWorld.</code>, 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-self-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 <code>onPrivateMsg</code> callback, which will answer <code>Hello World</code> to anyone saying <code>Hello</code> in a private message to SPADS:
<syntaxhighlight lang="python">
# This is the callback called each time SPADS receives a private message
# 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
def onPrivateMsg(self,userName,message):

# Here we "fix" strings received from Perl in case
# the Inline::Python module transmits them as byte strings
(userName,message)=spads.fix_string(userName,message)

# We check the message sent by the user is "Hello"
if message == 'Hello':

# We send our wonderful Hello World message
spads.sayPrivate(userName,'Hello World')

# We return 0 because we don't want to filter out private messages
# for other SPADS processing
return 0</syntaxhighlight>

All we have to do now is adding this callback declaration in our <code>helloworld.py</code> file located in SPADS plugins directory. We obtain [http://planetspads.free.fr/spads/plugins/tutorials/helloworld.py 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: <code>!plugin HelloWorld reload</code>. SPADS should answer <code>Reloaded plugin HelloWorld.</code>, which indicates the plugin has been reloaded successfully.

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

'''/!\ WORK IN PROGRESS /!\'''

 
= Configurable plugin tutorial (ForbiddenWords) =

In this section we are going to write our first configurable SPADS plugin (a configurable plugin has its own configuration file, named after the plugin name but with <code>.conf</code> extension). This plugin will monitor all messages said by players in the battle lobby, and will kick players who use swear words.

== Specifying our configuration parameters ==

The first step of writing a configurable plugin is to choose how we will configure it. In our example, we will use 2 configuration parameters: <code>words</code> will contain the list of forbidden words, and <code>immuneLevel</code> will contain the minimum autohost access level to be immune regarding these forbidden words checks.

We choose to make <code>words</code> a global setting (unmodifiable, not impacted by preset change), and <code>immuneLevel</code> a preset setting (modifiable, can be impacted by preset change). The <code>words</code> global setting will have no restriction (can be empty, can contain any character...), whereas the <code>immuneLevel</code> preset setting will only be allowed to be an integer or integer range.

== Preparing the template ==

Once we have a clear view of our configuration settings, we can start adapting the template for our needs. Since we are making a configurable plugin, this time we will download [http://planetspads.free.fr/spads/plugins/templates/commented/myconfigurableplugin.py the configurable plugin template] and its associated [http://planetspads.free.fr/spads/plugins/templates/commented/MyConfigurablePlugin.conf configuration file example].

First, let's take a look at the configuration file example. This is a just a basic configuration file containing one global setting example and one preset setting example. Let's modify this file to match the configuration we chose as follows (don't forget to rename the file from <code>MyConfigurablePlugin.conf</code> to <code>ForbiddenWords.conf</code> also):
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# This is our global setting (can't be changed without reloading the configuration)
words:ass;asshole;bastard;bitch;cunt;fuck;motherfucker;shit;whore

# We must define our preset setting in the default preset at least
[default]

# This is our preset setting, which can be changed with "!plugin ... set ..."
# or by loading a preset.
# "100" is the default value, and any integer between 0 and 140 is allowed
immuneLevel:100|0-140
|}
Then we must prepare the plugin template itself, by renaming it from <code>myconfigurableplugin.py</code> to <code>forbiddenwords.py</code> and editing it to replace <code>MyConfigurablePlugin</code> by <code>ForbiddenWords</code> in the source code. We must also adapt the template so that it uses the configuration settings we chose. This is done by modifying the <code>globalPluginParams</code> and <code>presetPluginParam</code> declarations as follows:
<syntaxhighlight lang="python">
# We define one global setting "words" and one preset setting "immuneLevel".
# "words" has no type associated (no restriction on allowed values)
# "immuneLevel" must be an integer or an integer range
# (check %paramTypes hash in SpadsConf.pm for a complete list of allowed
# setting types)
globalPluginParams = { 'words': [] }
presetPluginParams = { 'immuneLevel': ['integer','integerRange'] }
</syntaxhighlight>

== Writing plugin code ==

We want our plugin to react to messages said in the battle lobby. There is no dedicated callback for this event in [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html SPADS plugin API documentation], so we have to set up our own handler on the [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#SAIDBATTLE:server SAIDBATTLE lobby command]. To do so we have to call the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addLobbyCommandHandler-handlers-priority-caller addLobbyCommandHandler]. We will call this function at the end of our plugin constructor as follows, so that it will be set up directly when the plugin is loaded:
<syntaxhighlight lang="python">
[...]

# We set up a lobby command handler on SAIDBATTLE
addLobbyCommandHandler({SAIDBATTLE => \&hLobbySaidBattle});

# We return the instantiated plugin
return $self;

}
</syntaxhighlight>
However, if SPADS is disconnected from the lobby due to network problems for example, all lobby handlers are automatically removed. So we must re-add them each time we connect to lobby server. This can be done using the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onLobbyConnected-self-lobbyInterface onLobbyConnected] event-based callback as follows:
<syntaxhighlight lang="python">
# This callback is called each time we (re)connect to the lobby server
sub onLobbyConnected {

# When we are disconnected from the lobby server, all lobby command
# handlers are automatically removed, so we (re)set up our command
# handler here.
addLobbyCommandHandler({SAIDBATTLE => \&hLobbySaidBattle});

}
</syntaxhighlight>
Also, it is a good practice to remove any handler we have added when the plugin is unloaded. To do so we must implement the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback as follows:
<syntaxhighlight lang="python">
# This callback is called when the plugin is unloaded
sub onUnload {

# We remove our lobby command handler when the plugin is unloaded
removeLobbyCommandHandler(['SAIDBATTLE']);

}
</syntaxhighlight>
Finally, we have to implement our <code>SAIDBATTLE</code> handler <code>hLobbySaidBattle</code>. In this handler we need to perform following operations:
* skip processing if the user is the autohost itself: we need to access SPADS configuration to compare the user name with the [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:lobbyLogin lobbyLogin] setting value. So we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getSpadsConf getSpadsConf].
* perform processing according to our configuration (<code>words</code> and <code>immuneLevel</code> settings): we need to access our plugin configuration, so we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getPluginConf-pluginName-caller getPluginConf].
* retrieve the autohost access level of the user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getUserAccessLevel-user getUserAccessLevel]
* send a message to the battle lobby when we kick someone: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#sayBattle-message sayBattle].
* send a [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#KICKFROMBATTLE:client KICKFROMBATTLE] lobby command to kick a user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#queueLobbyCommand-lobbyCommand queueLobbyCommand].

Here is a commented implementation example of this <code>hLobbySaidBattle</code> handler, which will kick any non-privileged user saying a forbidden word in the battle lobby:
<syntaxhighlight lang="python">
# This is the handler we set up on SAIDBATTLE lobby command.
# It is called each time a player says something in the battle lobby.
sub hLobbySaidBattle {

# $command is the lobby command name (SAIDBATTLE)
# $user is the name of the user who said something in the battle lobby
# $message is the message said in the battle lobby
my ($command,$user,$message)=@_;

# First we check it's not a message from SPADS (so we don't kick ourself)
my $p_spadsConf=getSpadsConf();
return if($user eq $p_spadsConf->{lobbyLogin});

# Then we check the user isn't a privileged user
# (autohost access level >= immuneLevel)
my $p_conf=getPluginConf();
return if(getUserAccessLevel($user) >= $p_conf->{immuneLevel});

# We put the forbidden words in a array
my @forbiddenWords=split(/;/,$p_conf->{words});

# We test each forbidden word
foreach my $forbiddenWord (@forbiddenWords) {

# If the message contains the forbidden word (case insensitive)
if($message =~ /\b$forbiddenWord\b/i) {

# Then we kick the user from the battle lobby
sayBattle("Kicking $user from battle (watch your language!)");
queueLobbyCommand(["KICKFROMBATTLE",$user]);

# We quit the foreach loop (no need to test other forbidden word)
last;

}

}

}
</syntaxhighlight>
Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/forbiddenwords.py this fully functional ForbiddenWords] plugin and [http://planetspads.free.fr/spads/plugins/tutorials/ForbiddenWords.conf its associated configuration file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the associated configuration file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: <code>!plugin ForbiddenWords load</code>. And finally, as an unprivileged user we can try to say some forbidden words in the battle lobby and we should get kicked by the plugin.

 

= New-command plugin tutorial (TimePlugin) =

In this section we are going to write a plugin which implements a new command for SPADS. Such plugins are configurable plugins like the one we wrote just before, with 2 additional files to configure the new commands. This plugin will give current time when someone types <code>!time</code>.

== Preparing the template ==

This time we need to download 4 files to prepare our plugin: [http://planetspads.free.fr/spads/plugins/templates/commented/mynewcommandplugin.py the new-command plugin template], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPlugin.conf the associated configuration file example], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginHelp.dat the help file example] and [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginCmd.conf the commands rights configuration file example].

As usual, we rename these files to match our plugin name: <code>MyNewCommandPlugin</code> --> <code>TimePlugin</code>. Then we edit the plugin template <code>timeplugin.py</code> and replace <code>MyNewCommandPlugin</code> by <code>TimePlugin</code> in the source code, and we do the same for the plugin configuration template <code>TimePlugin.conf</code>, so that the <code>commandsFile</code> and <code>helpFile</code> settings are consistent with the files we just renamed.

Then we can edit our command rights requirements configuration file: <code>TimePluginCmd.conf</code>. This file uses the same syntax as the standard SPADS <code>commands.conf</code> file. The template provides a default command <code>myCommand</code> with no requirement. We will just rename this command to <code>time</code>:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# Anyone can call our command from anywhere
[time]
::|0:
|}
Now we need to write the help information for our new command. This is done in the file <code>TimePluginHelp.dat</code>. This file uses the same syntax as the standard SPADS <code>help.dat</code> file, and the template provides a help example for a command <code>myCommand</code> as a syntax reminder. After each command declaration, the first line is the command syntax description, and the other lines are optional usage examples. Let's replace this help example with our own help information for our basic <code>!time</code> command:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
[time]
<nowiki>!</nowiki>time - This command just prints current time
|}
== Writing plugin code ==

The new-command plugin template that we used to initialize our plugin already defines a new command named <code>myCommand</code>, so all we have to do is to edit our plugin file ( <code>timeplugin.py</code> ) and replace this command by our own <code>time</code> command:

First, let's modify the code which sets up the new SPADS command handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addSpadsCommandHandler-handlers-replace-0 addSpadsCommandHandler]. This call is located in the plugin constructor. We edit it so that it becomes:
<syntaxhighlight lang="python">
[...]
# We declare our new command and the associated handler
addSpadsCommandHandler({time => \&hSpadsTime});
[...]
</syntaxhighlight>
We must modify the same way the code which removes this SPADS handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#removeSpadsCommandHandler-commands removeSpadsCommandHandler] in the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback:
<syntaxhighlight lang="python">
[...]
# We remove our new command handler
removeSpadsCommandHandler(['time']);
[...]
</syntaxhighlight>
Finally, we must replace the handler example <code>hMyCommand</code> by our own handler <code>hSpadsTime</code>. In order to answer to the user issuing the command, we can use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#answer-message answer], which will send an answer message to the user in the same way he sent the command (private message, battle lobby...).

Here is an implementation example for this basic command:
<syntaxhighlight lang="python">
# This is the handler for our new command
sub hSpadsTime {
my ($source,$user,$p_params,$checkOnly)=@_;

# time is a basic command, we have nothing to check in case of callvote
return 1 if($checkOnly);

my @time = localtime();
@time = map(sprintf("%02d",$_),@time);

answer("Current local time: $time[2]:$time[1]:$time[0]");
}
</syntaxhighlight>

Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/timeplugin.py this fully functional TimePlugin] plugin, and its associated [http://planetspads.free.fr/spads/plugins/tutorials/TimePlugin.conf configuration file], [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginCmd.conf command rights configuration file] and [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginHelp.dat command help file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module and the plugin help file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the 2 configuration files in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: <code>!plugin TimePlugin load</code>. And finally, we can try to say !time in a private message to SPADS or in the battle lobby, and SPADS should answer giving current local time. Our <code>!time</code> command help should also appear in <code>!help</code> and <code>!help time</code> outputs.

[[Category:SPADS]]

SPADS plugin development (Python)

2021-01-28T11:03:19Z

Bibim: /* Preparing the template */

= Introduction =

SPADS is an autohost system coded in Perl, it supports both Perl and Python plugins. This tutorial deals with Python plugin development only (for Perl plugin development another tutorial is available [https://springrts.com/wiki/SPADS_plugin_development here]).

SPADS plugins are object-oriented modules. It is strongly recommended to already know Python basics before starting Python plugin development (a Python tutorial is available [https://docs.python.org/3/tutorial/ here]).

 
= Technical prerequisites =

Python (the Python interpreter and its libraries) must be installed on the system (versions 2.6+ or 3.2+ recommended). The type of installation (32-bit / 64-bit) must be consistent with the Perl version and the Spring engine used for SPADS.

Additionally, in order to allow communication between Perl code (SPADS core) and Python code (SPADS plugins), SPADS uses a Perl module named <code>Inline::Python</code> which must also be installed on the system. It is recommended to install the latest version for SPADS, refer to [https://springrts.com/wiki/SPADS_Inline::Python_installation_guide this guide] for installation.

 

= 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 [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] (the <code>.pm</code> files must be ignored for this tutorial, these are the Perl versions of the templates).

Our first plugin will be very basic, so we will use the simplest template: <code>mysimpleplugin.py</code>. Let's download [http://planetspads.free.fr/spads/plugins/templates/commented/mysimpleplugin.py 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 <code>HelloWorld</code>. We have to rename the downloaded template from <code>mysimpleplugin.py</code> to <code>helloworld.py</code>, and edit it to replace <code>MySimplePlugin</code> by <code>HelloWorld</code> 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 <code>spads.conf</code> configuration file and reload SPADS configuration).

We have to move our new plugin (<code>helloworld.py</code>) 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): <code>!plugin HelloWorld load</code>. SPADS should answer <code>Loaded plugin HelloWorld.</code>, 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-self-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 <code>onPrivateMsg</code> callback, which will answer <code>Hello World</code> to anyone saying <code>Hello</code> in a private message to SPADS:
<syntaxhighlight lang="python">
# This is the callback called each time SPADS receives a private message
# 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
def onPrivateMsg(self,userName,message):

# Here we "fix" strings received from Perl in case
# the Inline::Python module transmits them as byte strings
(userName,message)=spads.fix_string(userName,message)

# We check the message sent by the user is "Hello"
if message == 'Hello':

# We send our wonderful Hello World message
spads.sayPrivate(userName,'Hello World')

# We return 0 because we don't want to filter out private messages
# for other SPADS processing
return 0</syntaxhighlight>

All we have to do now is adding this callback declaration in our <code>helloworld.py</code> file located in SPADS plugins directory. We obtain [http://planetspads.free.fr/spads/plugins/tutorials/helloworld.py 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: <code>!plugin HelloWorld reload</code>. SPADS should answer <code>Reloaded plugin HelloWorld.</code>, which indicates the plugin has been reloaded successfully.

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

'''/!\ WORK IN PROGRESS /!\'''

 
= Configurable plugin tutorial (ForbiddenWords) =

In this section we are going to write our first configurable SPADS plugin (a configurable plugin has its own configuration file, named after the plugin name but with <code>.conf</code> extension). This plugin will monitor all messages said by players in the battle lobby, and will kick players who use swear words.

== Specifying our configuration parameters ==

The first step of writing a configurable plugin is to choose how we will configure it. In our example, we will use 2 configuration parameters: <code>words</code> will contain the list of forbidden words, and <code>immuneLevel</code> will contain the minimum autohost access level to be immune regarding these forbidden words checks.

We choose to make <code>words</code> a global setting (unmodifiable, not impacted by preset change), and <code>immuneLevel</code> a preset setting (modifiable, can be impacted by preset change). The <code>words</code> global setting will have no restriction (can be empty, can contain any character...), whereas the <code>immuneLevel</code> preset setting will only be allowed to be an integer or integer range.

== Preparing the template ==

Once we have a clear view of our configuration settings, we can start adapting the template for our needs. Since we are making a configurable plugin, this time we will download [http://planetspads.free.fr/spads/plugins/templates/commented/myconfigurableplugin.py the configurable plugin template] and its associated [http://planetspads.free.fr/spads/plugins/templates/commented/MyConfigurablePlugin.conf configuration file example].

First, let's take a look at the configuration file example. This is a just a basic configuration file containing one global setting example and one preset setting example. Let's modify this file to match the configuration we chose as follows (don't forget to rename the file from <code>MyConfigurablePlugin.conf</code> to <code>ForbiddenWords.conf</code> also):
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# This is our global setting (can't be changed without reloading the configuration)
words:ass;asshole;bastard;bitch;cunt;fuck;motherfucker;shit;whore

# We must define our preset setting in the default preset at least
[default]

# This is our preset setting, which can be changed with "!plugin ... set ..."
# or by loading a preset.
# "100" is the default value, and any integer between 0 and 140 is allowed
immuneLevel:100|0-140
|}
Then we must prepare the plugin template itself, by renaming it from <code>myconfigurableplugin.py</code> to <code>forbiddenwords.py</code> and editing it to replace <code>MyConfigurablePlugin</code> by <code>ForbiddenWords</code> in the source code. We must also adapt the template so that it uses the configuration settings we chose. This is done by modifying the <code>globalPluginParams</code> and <code>presetPluginParam</code> declarations as follows:
<syntaxhighlight lang="python">
# We define one global setting "words" and one preset setting "immuneLevel".
# "words" has no type associated (no restriction on allowed values)
# "immuneLevel" must be an integer or an integer range
# (check %paramTypes hash in SpadsConf.pm for a complete list of allowed
# setting types)
my %globalPluginParams = ( words => [] );
my %presetPluginParams = ( immuneLevel => ['integer','integerRange'] );
</syntaxhighlight>

== Writing plugin code ==

We want our plugin to react to messages said in the battle lobby. There is no dedicated callback for this event in [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html SPADS plugin API documentation], so we have to set up our own handler on the [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#SAIDBATTLE:server SAIDBATTLE lobby command]. To do so we have to call the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addLobbyCommandHandler-handlers-priority-caller addLobbyCommandHandler]. We will call this function at the end of our plugin constructor as follows, so that it will be set up directly when the plugin is loaded:
<syntaxhighlight lang="python">
[...]

# We set up a lobby command handler on SAIDBATTLE
addLobbyCommandHandler({SAIDBATTLE => \&hLobbySaidBattle});

# We return the instantiated plugin
return $self;

}
</syntaxhighlight>
However, if SPADS is disconnected from the lobby due to network problems for example, all lobby handlers are automatically removed. So we must re-add them each time we connect to lobby server. This can be done using the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onLobbyConnected-self-lobbyInterface onLobbyConnected] event-based callback as follows:
<syntaxhighlight lang="python">
# This callback is called each time we (re)connect to the lobby server
sub onLobbyConnected {

# When we are disconnected from the lobby server, all lobby command
# handlers are automatically removed, so we (re)set up our command
# handler here.
addLobbyCommandHandler({SAIDBATTLE => \&hLobbySaidBattle});

}
</syntaxhighlight>
Also, it is a good practice to remove any handler we have added when the plugin is unloaded. To do so we must implement the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback as follows:
<syntaxhighlight lang="python">
# This callback is called when the plugin is unloaded
sub onUnload {

# We remove our lobby command handler when the plugin is unloaded
removeLobbyCommandHandler(['SAIDBATTLE']);

}
</syntaxhighlight>
Finally, we have to implement our <code>SAIDBATTLE</code> handler <code>hLobbySaidBattle</code>. In this handler we need to perform following operations:
* skip processing if the user is the autohost itself: we need to access SPADS configuration to compare the user name with the [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:lobbyLogin lobbyLogin] setting value. So we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getSpadsConf getSpadsConf].
* perform processing according to our configuration (<code>words</code> and <code>immuneLevel</code> settings): we need to access our plugin configuration, so we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getPluginConf-pluginName-caller getPluginConf].
* retrieve the autohost access level of the user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getUserAccessLevel-user getUserAccessLevel]
* send a message to the battle lobby when we kick someone: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#sayBattle-message sayBattle].
* send a [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#KICKFROMBATTLE:client KICKFROMBATTLE] lobby command to kick a user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#queueLobbyCommand-lobbyCommand queueLobbyCommand].

Here is a commented implementation example of this <code>hLobbySaidBattle</code> handler, which will kick any non-privileged user saying a forbidden word in the battle lobby:
<syntaxhighlight lang="python">
# This is the handler we set up on SAIDBATTLE lobby command.
# It is called each time a player says something in the battle lobby.
sub hLobbySaidBattle {

# $command is the lobby command name (SAIDBATTLE)
# $user is the name of the user who said something in the battle lobby
# $message is the message said in the battle lobby
my ($command,$user,$message)=@_;

# First we check it's not a message from SPADS (so we don't kick ourself)
my $p_spadsConf=getSpadsConf();
return if($user eq $p_spadsConf->{lobbyLogin});

# Then we check the user isn't a privileged user
# (autohost access level >= immuneLevel)
my $p_conf=getPluginConf();
return if(getUserAccessLevel($user) >= $p_conf->{immuneLevel});

# We put the forbidden words in a array
my @forbiddenWords=split(/;/,$p_conf->{words});

# We test each forbidden word
foreach my $forbiddenWord (@forbiddenWords) {

# If the message contains the forbidden word (case insensitive)
if($message =~ /\b$forbiddenWord\b/i) {

# Then we kick the user from the battle lobby
sayBattle("Kicking $user from battle (watch your language!)");
queueLobbyCommand(["KICKFROMBATTLE",$user]);

# We quit the foreach loop (no need to test other forbidden word)
last;

}

}

}
</syntaxhighlight>
Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/forbiddenwords.py this fully functional ForbiddenWords] plugin and [http://planetspads.free.fr/spads/plugins/tutorials/ForbiddenWords.conf its associated configuration file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the associated configuration file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: <code>!plugin ForbiddenWords load</code>. And finally, as an unprivileged user we can try to say some forbidden words in the battle lobby and we should get kicked by the plugin.

 

= New-command plugin tutorial (TimePlugin) =

In this section we are going to write a plugin which implements a new command for SPADS. Such plugins are configurable plugins like the one we wrote just before, with 2 additional files to configure the new commands. This plugin will give current time when someone types <code>!time</code>.

== Preparing the template ==

This time we need to download 4 files to prepare our plugin: [http://planetspads.free.fr/spads/plugins/templates/commented/mynewcommandplugin.py the new-command plugin template], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPlugin.conf the associated configuration file example], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginHelp.dat the help file example] and [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginCmd.conf the commands rights configuration file example].

As usual, we rename these files to match our plugin name: <code>MyNewCommandPlugin</code> --> <code>TimePlugin</code>. Then we edit the plugin template <code>timeplugin.py</code> and replace <code>MyNewCommandPlugin</code> by <code>TimePlugin</code> in the source code, and we do the same for the plugin configuration template <code>TimePlugin.conf</code>, so that the <code>commandsFile</code> and <code>helpFile</code> settings are consistent with the files we just renamed.

Then we can edit our command rights requirements configuration file: <code>TimePluginCmd.conf</code>. This file uses the same syntax as the standard SPADS <code>commands.conf</code> file. The template provides a default command <code>myCommand</code> with no requirement. We will just rename this command to <code>time</code>:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# Anyone can call our command from anywhere
[time]
::|0:
|}
Now we need to write the help information for our new command. This is done in the file <code>TimePluginHelp.dat</code>. This file uses the same syntax as the standard SPADS <code>help.dat</code> file, and the template provides a help example for a command <code>myCommand</code> as a syntax reminder. After each command declaration, the first line is the command syntax description, and the other lines are optional usage examples. Let's replace this help example with our own help information for our basic <code>!time</code> command:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
[time]
<nowiki>!</nowiki>time - This command just prints current time
|}
== Writing plugin code ==

The new-command plugin template that we used to initialize our plugin already defines a new command named <code>myCommand</code>, so all we have to do is to edit our plugin file ( <code>timeplugin.py</code> ) and replace this command by our own <code>time</code> command:

First, let's modify the code which sets up the new SPADS command handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addSpadsCommandHandler-handlers-replace-0 addSpadsCommandHandler]. This call is located in the plugin constructor. We edit it so that it becomes:
<syntaxhighlight lang="python">
[...]
# We declare our new command and the associated handler
addSpadsCommandHandler({time => \&hSpadsTime});
[...]
</syntaxhighlight>
We must modify the same way the code which removes this SPADS handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#removeSpadsCommandHandler-commands removeSpadsCommandHandler] in the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback:
<syntaxhighlight lang="python">
[...]
# We remove our new command handler
removeSpadsCommandHandler(['time']);
[...]
</syntaxhighlight>
Finally, we must replace the handler example <code>hMyCommand</code> by our own handler <code>hSpadsTime</code>. In order to answer to the user issuing the command, we can use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#answer-message answer], which will send an answer message to the user in the same way he sent the command (private message, battle lobby...).

Here is an implementation example for this basic command:
<syntaxhighlight lang="python">
# This is the handler for our new command
sub hSpadsTime {
my ($source,$user,$p_params,$checkOnly)=@_;

# time is a basic command, we have nothing to check in case of callvote
return 1 if($checkOnly);

my @time = localtime();
@time = map(sprintf("%02d",$_),@time);

answer("Current local time: $time[2]:$time[1]:$time[0]");
}
</syntaxhighlight>

Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/timeplugin.py this fully functional TimePlugin] plugin, and its associated [http://planetspads.free.fr/spads/plugins/tutorials/TimePlugin.conf configuration file], [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginCmd.conf command rights configuration file] and [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginHelp.dat command help file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module and the plugin help file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the 2 configuration files in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: <code>!plugin TimePlugin load</code>. And finally, we can try to say !time in a private message to SPADS or in the battle lobby, and SPADS should answer giving current local time. Our <code>!time</code> command help should also appear in <code>!help</code> and <code>!help time</code> outputs.

[[Category:SPADS]]

SPADS plugin development (Python)

2021-01-28T10:53:00Z

Bibim: /* New-command plugin tutorial (TimePlugin) */

= Introduction =

SPADS is an autohost system coded in Perl, it supports both Perl and Python plugins. This tutorial deals with Python plugin development only (for Perl plugin development another tutorial is available [https://springrts.com/wiki/SPADS_plugin_development here]).

SPADS plugins are object-oriented modules. It is strongly recommended to already know Python basics before starting Python plugin development (a Python tutorial is available [https://docs.python.org/3/tutorial/ here]).

 
= Technical prerequisites =

Python (the Python interpreter and its libraries) must be installed on the system (versions 2.6+ or 3.2+ recommended). The type of installation (32-bit / 64-bit) must be consistent with the Perl version and the Spring engine used for SPADS.

Additionally, in order to allow communication between Perl code (SPADS core) and Python code (SPADS plugins), SPADS uses a Perl module named <code>Inline::Python</code> which must also be installed on the system. It is recommended to install the latest version for SPADS, refer to [https://springrts.com/wiki/SPADS_Inline::Python_installation_guide this guide] for installation.

 

= 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 [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] (the <code>.pm</code> files must be ignored for this tutorial, these are the Perl versions of the templates).

Our first plugin will be very basic, so we will use the simplest template: <code>mysimpleplugin.py</code>. Let's download [http://planetspads.free.fr/spads/plugins/templates/commented/mysimpleplugin.py 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 <code>HelloWorld</code>. We have to rename the downloaded template from <code>mysimpleplugin.py</code> to <code>helloworld.py</code>, and edit it to replace <code>MySimplePlugin</code> by <code>HelloWorld</code> 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 <code>spads.conf</code> configuration file and reload SPADS configuration).

We have to move our new plugin (<code>helloworld.py</code>) 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): <code>!plugin HelloWorld load</code>. SPADS should answer <code>Loaded plugin HelloWorld.</code>, 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-self-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 <code>onPrivateMsg</code> callback, which will answer <code>Hello World</code> to anyone saying <code>Hello</code> in a private message to SPADS:
<syntaxhighlight lang="python">
# This is the callback called each time SPADS receives a private message
# 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
def onPrivateMsg(self,userName,message):

# Here we "fix" strings received from Perl in case
# the Inline::Python module transmits them as byte strings
(userName,message)=spads.fix_string(userName,message)

# We check the message sent by the user is "Hello"
if message == 'Hello':

# We send our wonderful Hello World message
spads.sayPrivate(userName,'Hello World')

# We return 0 because we don't want to filter out private messages
# for other SPADS processing
return 0</syntaxhighlight>

All we have to do now is adding this callback declaration in our <code>helloworld.py</code> file located in SPADS plugins directory. We obtain [http://planetspads.free.fr/spads/plugins/tutorials/helloworld.py 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: <code>!plugin HelloWorld reload</code>. SPADS should answer <code>Reloaded plugin HelloWorld.</code>, which indicates the plugin has been reloaded successfully.

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

'''/!\ WORK IN PROGRESS /!\'''

 
= Configurable plugin tutorial (ForbiddenWords) =

In this section we are going to write our first configurable SPADS plugin (a configurable plugin has its own configuration file, named after the plugin name but with <code>.conf</code> extension). This plugin will monitor all messages said by players in the battle lobby, and will kick players who use swear words.

== Specifying our configuration parameters ==

The first step of writing a configurable plugin is to choose how we will configure it. In our example, we will use 2 configuration parameters: <code>words</code> will contain the list of forbidden words, and <code>immuneLevel</code> will contain the minimum autohost access level to be immune regarding these forbidden words checks.

We choose to make <code>words</code> a global setting (unmodifiable, not impacted by preset change), and <code>immuneLevel</code> a preset setting (modifiable, can be impacted by preset change). The <code>words</code> global setting will have no restriction (can be empty, can contain any character...), whereas the <code>immuneLevel</code> preset setting will only be allowed to be an integer or integer range.

== Preparing the template ==

Once we have a clear view of our configuration settings, we can start adapting the template for our needs. Since we are making a configurable plugin, this time we will download [http://planetspads.free.fr/spads/plugins/templates/commented/myconfigurableplugin.py the configurable plugin template] and its associated [http://planetspads.free.fr/spads/plugins/templates/commented/MyConfigurablePlugin.conf configuration file example].

First, let's take a look at the configuration file example. This is a just a basic configuration file containing one global setting example and one preset setting example. Let's modify this file to match the configuration we chose as follows (don't forget to rename the file from <code>MyConfigurablePlugin.conf</code> to <code>ForbiddenWords.conf</code> also):
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# This is our global setting (can't be changed without reloading the configuration)
words:ass;asshole;bastard;bitch;cunt;fuck;motherfucker;shit;whore

# We must define our preset setting in the default preset at least
[default]

# This is our preset setting, which can be changed with "!plugin ... set ..."
# or by loading a preset.
# "100" is the default value, and any integer between 0 and 140 is allowed
immuneLevel:100|0-140
|}
Then we must prepare the plugin template itself, by renaming it from <code>myconfigurableplugin.py</code> to <code>forbiddenwords.py</code> and editing it to replace <code>MyConfigurablePlugin</code> by <code>ForbiddenWords</code> in the source code. We must also adapt the template so that it uses the configuration settings we chose. This is done by modifying the <code>globalPluginParams</code> and <code>presetPluginParam</code> declarations as follows:
<syntaxhighlight lang="python">
# We define one global setting "words" and one preset setting "immuneLevel".
# "words" has no type associated (no restriction on allowed values)
# "immuneLevel" must be an integer or an integer range
# (check %paramTypes hash in SpadsConf.pm for a complete list of allowed
# setting types)
my %globalPluginParams = ( words => [] );
my %presetPluginParams = ( immuneLevel => ['integer','integerRange'] );
</syntaxhighlight>

== Writing plugin code ==

We want our plugin to react to messages said in the battle lobby. There is no dedicated callback for this event in [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html SPADS plugin API documentation], so we have to set up our own handler on the [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#SAIDBATTLE:server SAIDBATTLE lobby command]. To do so we have to call the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addLobbyCommandHandler-handlers-priority-caller addLobbyCommandHandler]. We will call this function at the end of our plugin constructor as follows, so that it will be set up directly when the plugin is loaded:
<syntaxhighlight lang="python">
[...]

# We set up a lobby command handler on SAIDBATTLE
addLobbyCommandHandler({SAIDBATTLE => \&hLobbySaidBattle});

# We return the instantiated plugin
return $self;

}
</syntaxhighlight>
However, if SPADS is disconnected from the lobby due to network problems for example, all lobby handlers are automatically removed. So we must re-add them each time we connect to lobby server. This can be done using the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onLobbyConnected-self-lobbyInterface onLobbyConnected] event-based callback as follows:
<syntaxhighlight lang="python">
# This callback is called each time we (re)connect to the lobby server
sub onLobbyConnected {

# When we are disconnected from the lobby server, all lobby command
# handlers are automatically removed, so we (re)set up our command
# handler here.
addLobbyCommandHandler({SAIDBATTLE => \&hLobbySaidBattle});

}
</syntaxhighlight>
Also, it is a good practice to remove any handler we have added when the plugin is unloaded. To do so we must implement the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback as follows:
<syntaxhighlight lang="python">
# This callback is called when the plugin is unloaded
sub onUnload {

# We remove our lobby command handler when the plugin is unloaded
removeLobbyCommandHandler(['SAIDBATTLE']);

}
</syntaxhighlight>
Finally, we have to implement our <code>SAIDBATTLE</code> handler <code>hLobbySaidBattle</code>. In this handler we need to perform following operations:
* skip processing if the user is the autohost itself: we need to access SPADS configuration to compare the user name with the [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:lobbyLogin lobbyLogin] setting value. So we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getSpadsConf getSpadsConf].
* perform processing according to our configuration (<code>words</code> and <code>immuneLevel</code> settings): we need to access our plugin configuration, so we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getPluginConf-pluginName-caller getPluginConf].
* retrieve the autohost access level of the user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getUserAccessLevel-user getUserAccessLevel]
* send a message to the battle lobby when we kick someone: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#sayBattle-message sayBattle].
* send a [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#KICKFROMBATTLE:client KICKFROMBATTLE] lobby command to kick a user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#queueLobbyCommand-lobbyCommand queueLobbyCommand].

Here is a commented implementation example of this <code>hLobbySaidBattle</code> handler, which will kick any non-privileged user saying a forbidden word in the battle lobby:
<syntaxhighlight lang="python">
# This is the handler we set up on SAIDBATTLE lobby command.
# It is called each time a player says something in the battle lobby.
sub hLobbySaidBattle {

# $command is the lobby command name (SAIDBATTLE)
# $user is the name of the user who said something in the battle lobby
# $message is the message said in the battle lobby
my ($command,$user,$message)=@_;

# First we check it's not a message from SPADS (so we don't kick ourself)
my $p_spadsConf=getSpadsConf();
return if($user eq $p_spadsConf->{lobbyLogin});

# Then we check the user isn't a privileged user
# (autohost access level >= immuneLevel)
my $p_conf=getPluginConf();
return if(getUserAccessLevel($user) >= $p_conf->{immuneLevel});

# We put the forbidden words in a array
my @forbiddenWords=split(/;/,$p_conf->{words});

# We test each forbidden word
foreach my $forbiddenWord (@forbiddenWords) {

# If the message contains the forbidden word (case insensitive)
if($message =~ /\b$forbiddenWord\b/i) {

# Then we kick the user from the battle lobby
sayBattle("Kicking $user from battle (watch your language!)");
queueLobbyCommand(["KICKFROMBATTLE",$user]);

# We quit the foreach loop (no need to test other forbidden word)
last;

}

}

}
</syntaxhighlight>
Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/forbiddenwords.py this fully functional ForbiddenWords] plugin and [http://planetspads.free.fr/spads/plugins/tutorials/ForbiddenWords.conf its associated configuration file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the associated configuration file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: <code>!plugin ForbiddenWords load</code>. And finally, as an unprivileged user we can try to say some forbidden words in the battle lobby and we should get kicked by the plugin.

 

= New-command plugin tutorial (TimePlugin) =

In this section we are going to write a plugin which implements a new command for SPADS. Such plugins are configurable plugins like the one we wrote just before, with 2 additional files to configure the new commands. This plugin will give current time when someone types <code>!time</code>.

== Preparing the template ==

This time we need to download 4 files to prepare our plugin: [http://planetspads.free.fr/spads/plugins/templates/commented/mynewcommandplugin.py the new-command plugin template], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPlugin.conf the associated configuration file example], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginHelp.dat the help file example] and [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginCmd.conf the commands rights configuration file example].

As usual, we rename these files to match our plugin name: <code>MyNewCommandPlugin</code> --> <code>TimePlugin</code>. Then we edit the plugin template <code>timeplugin.py</code> and replace <code>MyNewCommandPlugin</code> by <code>TimePlugin</code> in the source code, and we do the same for the plugin configuration template <code>TimePlugin.conf</code>, so that the <code>commandsFile</code> and <code>helpFile</code> settings are consistent with the files we just renamed.

Then we can edit our command rights requirements configuration file: <code>TimePluginCmd.conf</code>. This file uses the same syntax as the standard SPADS <code>commands.conf</code> file. The template provides a default command <code>myCommand</code> with no requirement. We will just rename this command to <code>time</code>:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# Anyone can call our command from anywhere
[time]
::|0:
|}
Now we need to write the help information for our new command. This is done in the file <code>TimePluginHelp.dat</code>. This file uses the same syntax as the standard SPADS <code>help.dat</code> file, and the template provides a help example for a command <code>myCommand</code> as a syntax reminder. After each command declaration, the first line is the command syntax description, and the other lines are optional usage examples. Let's replace this help example with our own help information for our basic <code>!time</code> command:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
[time]
<nowiki>!</nowiki>time - This command just prints current time
|}
== Writing plugin code ==

The new-command plugin template that we used to initialize our plugin already defines a new command named <code>myCommand</code>, so all we have to do is to edit our plugin file ( <code>timeplugin.py</code> ) and replace this command by our own <code>time</code> command:

First, let's modify the code which sets up the new SPADS command handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addSpadsCommandHandler-handlers-replace-0 addSpadsCommandHandler]. This call is located in the plugin constructor. We edit it so that it becomes:
<syntaxhighlight lang="python">
[...]
# We declare our new command and the associated handler
addSpadsCommandHandler({time => \&hSpadsTime});
[...]
</syntaxhighlight>
We must modify the same way the code which removes this SPADS handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#removeSpadsCommandHandler-commands removeSpadsCommandHandler] in the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback:
<syntaxhighlight lang="python">
[...]
# We remove our new command handler
removeSpadsCommandHandler(['time']);
[...]
</syntaxhighlight>
Finally, we must replace the handler example <code>hMyCommand</code> by our own handler <code>hSpadsTime</code>. In order to answer to the user issuing the command, we can use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#answer-message answer], which will send an answer message to the user in the same way he sent the command (private message, battle lobby...).

Here is an implementation example for this basic command:
<syntaxhighlight lang="python">
# This is the handler for our new command
sub hSpadsTime {
my ($source,$user,$p_params,$checkOnly)=@_;

# time is a basic command, we have nothing to check in case of callvote
return 1 if($checkOnly);

my @time = localtime();
@time = map(sprintf("%02d",$_),@time);

answer("Current local time: $time[2]:$time[1]:$time[0]");
}
</syntaxhighlight>

Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/timeplugin.py this fully functional TimePlugin] plugin, and its associated [http://planetspads.free.fr/spads/plugins/tutorials/TimePlugin.conf configuration file], [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginCmd.conf command rights configuration file] and [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginHelp.dat command help file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module and the plugin help file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the 2 configuration files in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: <code>!plugin TimePlugin load</code>. And finally, we can try to say !time in a private message to SPADS or in the battle lobby, and SPADS should answer giving current local time. Our <code>!time</code> command help should also appear in <code>!help</code> and <code>!help time</code> outputs.

[[Category:SPADS]]

SPADS plugin development

2021-01-28T10:49:12Z

Bibim: /* New-command plugin tutorial (TimePlugin) */

= Introduction =

SPADS is an autohost system coded in Perl, it supports both Perl and Python plugins. This tutorial deals with Perl plugin development only (for Python plugin development another tutorial is available [https://springrts.com/wiki/SPADS_plugin_development_(Python) here]).

SPADS plugins are object-oriented modules. It is strongly recommended to already know Perl basics before starting Perl plugin development (a brief introduction to Perl is available [https://perldoc.perl.org/perlintro here]).

 
= 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 [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] (the <code>.py</code> files must be ignored for this tutorial, these are the Python versions of the templates).

Our first plugin will be very basic, so we will use the simplest template: <code>MySimplePlugin.pm</code>. 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 <code>HelloWorld</code>. We have to rename the downloaded template from <code>MySimplePlugin.pm</code> to <code>HelloWorld.pm</code>, and edit it to replace <code>MySimplePlugin</code> by <code>HelloWorld</code> 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 <code>spads.conf</code> configuration file and reload SPADS configuration).

We have to move our new plugin (<code>HelloWorld.pm</code>) 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): <code>!plugin HelloWorld load</code>. SPADS should answer <code>Loaded plugin HelloWorld.</code>, 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-self-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 <code>onPrivateMsg</code> callback, which will answer <code>Hello World</code> to anyone saying <code>Hello</code> in a private message to SPADS:
<syntaxhighlight lang="perl">
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;

}</syntaxhighlight>

All we have to do now is adding this callback declaration in our <code>HelloWorld.pm</code> 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: <code>!plugin HelloWorld reload</code>. SPADS should answer <code>Reloaded plugin HelloWorld.</code>, which indicates the plugin has been reloaded successfully.

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

 
= Configurable plugin tutorial (ForbiddenWords) =

In this section we are going to write our first configurable SPADS plugin (a configurable plugin has its own configuration file, named after the plugin name but with <code>.conf</code> extension). This plugin will monitor all messages said by players in the battle lobby, and will kick players who use swear words.

== Specifying our configuration parameters ==

The first step of writing a configurable plugin is to choose how we will configure it. In our example, we will use 2 configuration parameters: <code>words</code> will contain the list of forbidden words, and <code>immuneLevel</code> will contain the minimum autohost access level to be immune regarding these forbidden words checks.

We choose to make <code>words</code> a global setting (unmodifiable, not impacted by preset change), and <code>immuneLevel</code> a preset setting (modifiable, can be impacted by preset change). The <code>words</code> global setting will have no restriction (can be empty, can contain any character...), whereas the <code>immuneLevel</code> preset setting will only be allowed to be an integer or integer range.

== Preparing the template ==

Once we have a clear view of our configuration settings, we can start adapting the template for our needs. Since we are making a configurable plugin, this time we will download [http://planetspads.free.fr/spads/plugins/templates/commented/MyConfigurablePlugin.pm the configurable plugin template] and its associated [http://planetspads.free.fr/spads/plugins/templates/commented/MyConfigurablePlugin.conf configuration file example].

First, let's take a look at the configuration file example. This is a just a basic configuration file containing one global setting example and one preset setting example. Let's modify this file to match the configuration we chose as follows (don't forget to rename the file from <code>MyConfigurablePlugin.conf</code> to <code>ForbiddenWords.conf</code> also):
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# This is our global setting (can't be changed without reloading the configuration)
words:ass;asshole;bastard;bitch;cunt;fuck;motherfucker;shit;whore

# We must define our preset setting in the default preset at least
[default]

# This is our preset setting, which can be changed with "!plugin ... set ..."
# or by loading a preset.
# "100" is the default value, and any integer between 0 and 140 is allowed
immuneLevel:100|0-140
|}
Then we must prepare the plugin template itself, by renaming it from <code>MyConfigurablePlugin.pm</code> to <code>ForbiddenWords.pm</code> and editing it to replace <code>MyConfigurablePlugin</code> by <code>ForbiddenWords</code> in the source code. We must also adapt the template so that it uses the configuration settings we chose. This is done by modifying the <code>%globalPluginParams</code> and <code>%presetPluginParam</code> declarations as follows:
<syntaxhighlight lang="perl">
# We define one global setting "words" and one preset setting "immuneLevel".
# "words" has no type associated (no restriction on allowed values)
# "immuneLevel" must be an integer or an integer range
# (check %paramTypes hash in SpadsConf.pm for a complete list of allowed
# setting types)
my %globalPluginParams = ( words => [] );
my %presetPluginParams = ( immuneLevel => ['integer','integerRange'] );
</syntaxhighlight>

== Writing plugin code ==

We want our plugin to react to messages said in the battle lobby. There is no dedicated callback for this event in [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html SPADS plugin API documentation], so we have to set up our own handler on the [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#SAIDBATTLE:server SAIDBATTLE lobby command]. To do so we have to call the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addLobbyCommandHandler-handlers-priority-caller addLobbyCommandHandler]. We will call this function at the end of our plugin constructor as follows, so that it will be set up directly when the plugin is loaded:
<syntaxhighlight lang="perl">
[...]

# We set up a lobby command handler on SAIDBATTLE
addLobbyCommandHandler({SAIDBATTLE => \&hLobbySaidBattle});

# We return the instantiated plugin
return $self;

}
</syntaxhighlight>
However, if SPADS is disconnected from the lobby due to network problems for example, all lobby handlers are automatically removed. So we must re-add them each time we connect to lobby server. This can be done using the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onLobbyConnected-self-lobbyInterface onLobbyConnected] event-based callback as follows:
<syntaxhighlight lang="perl">
# This callback is called each time we (re)connect to the lobby server
sub onLobbyConnected {

# When we are disconnected from the lobby server, all lobby command
# handlers are automatically removed, so we (re)set up our command
# handler here.
addLobbyCommandHandler({SAIDBATTLE => \&hLobbySaidBattle});

}
</syntaxhighlight>
Also, it is a good practice to remove any handler we have added when the plugin is unloaded. To do so we must implement the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback as follows:
<syntaxhighlight lang="perl">
# This callback is called when the plugin is unloaded
sub onUnload {

# We remove our lobby command handler when the plugin is unloaded
removeLobbyCommandHandler(['SAIDBATTLE']);

}
</syntaxhighlight>
Finally, we have to implement our <code>SAIDBATTLE</code> handler <code>hLobbySaidBattle</code>. In this handler we need to perform following operations:
* skip processing if the user is the autohost itself: we need to access SPADS configuration to compare the user name with the [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:lobbyLogin lobbyLogin] setting value. So we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getSpadsConf getSpadsConf].
* perform processing according to our configuration (<code>words</code> and <code>immuneLevel</code> settings): we need to access our plugin configuration, so we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getPluginConf-pluginName-caller getPluginConf].
* retrieve the autohost access level of the user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getUserAccessLevel-user getUserAccessLevel]
* send a message to the battle lobby when we kick someone: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#sayBattle-message sayBattle].
* send a [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#KICKFROMBATTLE:client KICKFROMBATTLE] lobby command to kick a user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#queueLobbyCommand-lobbyCommand queueLobbyCommand].

Here is a commented implementation example of this <code>hLobbySaidBattle</code> handler, which will kick any non-privileged user saying a forbidden word in the battle lobby:
<syntaxhighlight lang="perl">
# This is the handler we set up on SAIDBATTLE lobby command.
# It is called each time a player says something in the battle lobby.
sub hLobbySaidBattle {

# $command is the lobby command name (SAIDBATTLE)
# $user is the name of the user who said something in the battle lobby
# $message is the message said in the battle lobby
my ($command,$user,$message)=@_;

# First we check it's not a message from SPADS (so we don't kick ourself)
my $p_spadsConf=getSpadsConf();
return if($user eq $p_spadsConf->{lobbyLogin});

# Then we check the user isn't a privileged user
# (autohost access level >= immuneLevel)
my $p_conf=getPluginConf();
return if(getUserAccessLevel($user) >= $p_conf->{immuneLevel});

# We put the forbidden words in a array
my @forbiddenWords=split(/;/,$p_conf->{words});

# We test each forbidden word
foreach my $forbiddenWord (@forbiddenWords) {

# If the message contains the forbidden word (case insensitive)
if($message =~ /\b$forbiddenWord\b/i) {

# Then we kick the user from the battle lobby
sayBattle("Kicking $user from battle (watch your language!)");
queueLobbyCommand(["KICKFROMBATTLE",$user]);

# We quit the foreach loop (no need to test other forbidden word)
last;

}

}

}
</syntaxhighlight>
Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/ForbiddenWords.pm this fully functional ForbiddenWords] plugin and [http://planetspads.free.fr/spads/plugins/tutorials/ForbiddenWords.conf its associated configuration file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the associated configuration file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: <code>!plugin ForbiddenWords load</code>. And finally, as an unprivileged user we can try to say some forbidden words in the battle lobby and we should get kicked by the plugin.

 

= New-command plugin tutorial (TimePlugin) =

In this section we are going to write a plugin which implements a new command for SPADS. Such plugins are configurable plugins like the one we wrote just before, with 2 additional files to configure the new commands. This plugin will give current time when someone types <code>!time</code>.

== Preparing the template ==

This time we need to download 4 files to prepare our plugin: [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPlugin.pm the new-command plugin template], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPlugin.conf the associated configuration file example], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginHelp.dat the help file example] and [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginCmd.conf the commands rights configuration file example].

As usual, we rename these files to match our plugin name: <code>MyNewCommandPlugin</code> --> <code>TimePlugin</code>. Then we edit the plugin template <code>TimePlugin.pm</code> and replace <code>MyNewCommandPlugin</code> by <code>TimePlugin</code> in the source code, and we do the same for the plugin configuration template <code>TimePlugin.conf</code>, so that the <code>commandsFile</code> and <code>helpFile</code> settings are consistent with the files we just renamed.

Then we can edit our command rights requirements configuration file: <code>TimePluginCmd.conf</code>. This file uses the same syntax as the standard SPADS <code>commands.conf</code> file. The template provides a default command <code>myCommand</code> with no requirement. We will just rename this command to <code>time</code>:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# Anyone can call our command from anywhere
[time]
::|0:
|}
Now we need to write the help information for our new command. This is done in the file <code>TimePluginHelp.dat</code>. This file uses the same syntax as the standard SPADS <code>help.dat</code> file, and the template provides a help example for a command <code>myCommand</code> as a syntax reminder. After each command declaration, the first line is the command syntax description, and the other lines are optional usage examples. Let's replace this help example with our own help information for our basic <code>!time</code> command:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
[time]
<nowiki>!</nowiki>time - This command just prints current time
|}
== Writing plugin code ==

The new-command plugin template that we used to initialize our plugin already defines a new command named <code>myCommand</code>, so all we have to do is to edit our plugin file ( <code>TimePlugin.pm</code> ) and replace this command by our own <code>time</code> command:

First, let's modify the code which sets up the new SPADS command handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addSpadsCommandHandler-handlers-replace-0 addSpadsCommandHandler]. This call is located in the plugin constructor. We edit it so that it becomes:
<syntaxhighlight lang="perl">
[...]
# We declare our new command and the associated handler
addSpadsCommandHandler({time => \&hSpadsTime});
[...]
</syntaxhighlight>
We must modify the same way the code which removes this SPADS handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#removeSpadsCommandHandler-commands removeSpadsCommandHandler] in the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback:
<syntaxhighlight lang="perl">
[...]
# We remove our new command handler
removeSpadsCommandHandler(['time']);
[...]
</syntaxhighlight>
Finally, we must replace the handler example <code>hMyCommand</code> by our own handler <code>hSpadsTime</code>. In order to answer to the user issuing the command, we can use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#answer-message answer], which will send an answer message to the user in the same way he sent the command (private message, battle lobby...).

Here is an implementation example for this basic command:
<syntaxhighlight lang="perl">
# This is the handler for our new command
sub hSpadsTime {
my ($source,$user,$p_params,$checkOnly)=@_;

# time is a basic command, we have nothing to check in case of callvote
return 1 if($checkOnly);

my @time = localtime();
@time = map(sprintf("%02d",$_),@time);

answer("Current local time: $time[2]:$time[1]:$time[0]");
}
</syntaxhighlight>

Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/TimePlugin.pm this fully functional TimePlugin] plugin, and its associated [http://planetspads.free.fr/spads/plugins/tutorials/TimePlugin.conf configuration file], [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginCmd.conf command rights configuration file] and [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginHelp.dat command help file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module and the plugin help file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the 2 configuration files in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: <code>!plugin TimePlugin load</code>. And finally, we can try to say !time in a private message to SPADS or in the battle lobby, and SPADS should answer giving current local time. Our <code>!time</code> command help should also appear in <code>!help</code> and <code>!help time</code> outputs.

[[Category:SPADS]]

SPADS plugin development (Python)

2021-01-28T10:03:02Z

Bibim: /* Configurable plugin tutorial (ForbiddenWords) */

= Introduction =

SPADS is an autohost system coded in Perl, it supports both Perl and Python plugins. This tutorial deals with Python plugin development only (for Perl plugin development another tutorial is available [https://springrts.com/wiki/SPADS_plugin_development here]).

SPADS plugins are object-oriented modules. It is strongly recommended to already know Python basics before starting Python plugin development (a Python tutorial is available [https://docs.python.org/3/tutorial/ here]).

 
= Technical prerequisites =

Python (the Python interpreter and its libraries) must be installed on the system (versions 2.6+ or 3.2+ recommended). The type of installation (32-bit / 64-bit) must be consistent with the Perl version and the Spring engine used for SPADS.

Additionally, in order to allow communication between Perl code (SPADS core) and Python code (SPADS plugins), SPADS uses a Perl module named <code>Inline::Python</code> which must also be installed on the system. It is recommended to install the latest version for SPADS, refer to [https://springrts.com/wiki/SPADS_Inline::Python_installation_guide this guide] for installation.

 

= 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 [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] (the <code>.pm</code> files must be ignored for this tutorial, these are the Perl versions of the templates).

Our first plugin will be very basic, so we will use the simplest template: <code>mysimpleplugin.py</code>. Let's download [http://planetspads.free.fr/spads/plugins/templates/commented/mysimpleplugin.py 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 <code>HelloWorld</code>. We have to rename the downloaded template from <code>mysimpleplugin.py</code> to <code>helloworld.py</code>, and edit it to replace <code>MySimplePlugin</code> by <code>HelloWorld</code> 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 <code>spads.conf</code> configuration file and reload SPADS configuration).

We have to move our new plugin (<code>helloworld.py</code>) 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): <code>!plugin HelloWorld load</code>. SPADS should answer <code>Loaded plugin HelloWorld.</code>, 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-self-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 <code>onPrivateMsg</code> callback, which will answer <code>Hello World</code> to anyone saying <code>Hello</code> in a private message to SPADS:
<syntaxhighlight lang="python">
# This is the callback called each time SPADS receives a private message
# 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
def onPrivateMsg(self,userName,message):

# Here we "fix" strings received from Perl in case
# the Inline::Python module transmits them as byte strings
(userName,message)=spads.fix_string(userName,message)

# We check the message sent by the user is "Hello"
if message == 'Hello':

# We send our wonderful Hello World message
spads.sayPrivate(userName,'Hello World')

# We return 0 because we don't want to filter out private messages
# for other SPADS processing
return 0</syntaxhighlight>

All we have to do now is adding this callback declaration in our <code>helloworld.py</code> file located in SPADS plugins directory. We obtain [http://planetspads.free.fr/spads/plugins/tutorials/helloworld.py 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: <code>!plugin HelloWorld reload</code>. SPADS should answer <code>Reloaded plugin HelloWorld.</code>, which indicates the plugin has been reloaded successfully.

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

'''/!\ WORK IN PROGRESS /!\'''

 
= Configurable plugin tutorial (ForbiddenWords) =

In this section we are going to write our first configurable SPADS plugin (a configurable plugin has its own configuration file, named after the plugin name but with <code>.conf</code> extension). This plugin will monitor all messages said by players in the battle lobby, and will kick players who use swear words.

== Specifying our configuration parameters ==

The first step of writing a configurable plugin is to choose how we will configure it. In our example, we will use 2 configuration parameters: <code>words</code> will contain the list of forbidden words, and <code>immuneLevel</code> will contain the minimum autohost access level to be immune regarding these forbidden words checks.

We choose to make <code>words</code> a global setting (unmodifiable, not impacted by preset change), and <code>immuneLevel</code> a preset setting (modifiable, can be impacted by preset change). The <code>words</code> global setting will have no restriction (can be empty, can contain any character...), whereas the <code>immuneLevel</code> preset setting will only be allowed to be an integer or integer range.

== Preparing the template ==

Once we have a clear view of our configuration settings, we can start adapting the template for our needs. Since we are making a configurable plugin, this time we will download [http://planetspads.free.fr/spads/plugins/templates/commented/myconfigurableplugin.py the configurable plugin template] and its associated [http://planetspads.free.fr/spads/plugins/templates/commented/MyConfigurablePlugin.conf configuration file example].

First, let's take a look at the configuration file example. This is a just a basic configuration file containing one global setting example and one preset setting example. Let's modify this file to match the configuration we chose as follows (don't forget to rename the file from <code>MyConfigurablePlugin.conf</code> to <code>ForbiddenWords.conf</code> also):
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# This is our global setting (can't be changed without reloading the configuration)
words:ass;asshole;bastard;bitch;cunt;fuck;motherfucker;shit;whore

# We must define our preset setting in the default preset at least
[default]

# This is our preset setting, which can be changed with "!plugin ... set ..."
# or by loading a preset.
# "100" is the default value, and any integer between 0 and 140 is allowed
immuneLevel:100|0-140
|}
Then we must prepare the plugin template itself, by renaming it from <code>myconfigurableplugin.py</code> to <code>forbiddenwords.py</code> and editing it to replace <code>MyConfigurablePlugin</code> by <code>ForbiddenWords</code> in the source code. We must also adapt the template so that it uses the configuration settings we chose. This is done by modifying the <code>globalPluginParams</code> and <code>presetPluginParam</code> declarations as follows:
<syntaxhighlight lang="python">
# We define one global setting "words" and one preset setting "immuneLevel".
# "words" has no type associated (no restriction on allowed values)
# "immuneLevel" must be an integer or an integer range
# (check %paramTypes hash in SpadsConf.pm for a complete list of allowed
# setting types)
my %globalPluginParams = ( words => [] );
my %presetPluginParams = ( immuneLevel => ['integer','integerRange'] );
</syntaxhighlight>

== Writing plugin code ==

We want our plugin to react to messages said in the battle lobby. There is no dedicated callback for this event in [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html SPADS plugin API documentation], so we have to set up our own handler on the [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#SAIDBATTLE:server SAIDBATTLE lobby command]. To do so we have to call the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addLobbyCommandHandler-handlers-priority-caller addLobbyCommandHandler]. We will call this function at the end of our plugin constructor as follows, so that it will be set up directly when the plugin is loaded:
<syntaxhighlight lang="python">
[...]

# We set up a lobby command handler on SAIDBATTLE
addLobbyCommandHandler({SAIDBATTLE => \&hLobbySaidBattle});

# We return the instantiated plugin
return $self;

}
</syntaxhighlight>
However, if SPADS is disconnected from the lobby due to network problems for example, all lobby handlers are automatically removed. So we must re-add them each time we connect to lobby server. This can be done using the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onLobbyConnected-self-lobbyInterface onLobbyConnected] event-based callback as follows:
<syntaxhighlight lang="python">
# This callback is called each time we (re)connect to the lobby server
sub onLobbyConnected {

# When we are disconnected from the lobby server, all lobby command
# handlers are automatically removed, so we (re)set up our command
# handler here.
addLobbyCommandHandler({SAIDBATTLE => \&hLobbySaidBattle});

}
</syntaxhighlight>
Also, it is a good practice to remove any handler we have added when the plugin is unloaded. To do so we must implement the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback as follows:
<syntaxhighlight lang="python">
# This callback is called when the plugin is unloaded
sub onUnload {

# We remove our lobby command handler when the plugin is unloaded
removeLobbyCommandHandler(['SAIDBATTLE']);

}
</syntaxhighlight>
Finally, we have to implement our <code>SAIDBATTLE</code> handler <code>hLobbySaidBattle</code>. In this handler we need to perform following operations:
* skip processing if the user is the autohost itself: we need to access SPADS configuration to compare the user name with the [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:lobbyLogin lobbyLogin] setting value. So we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getSpadsConf getSpadsConf].
* perform processing according to our configuration (<code>words</code> and <code>immuneLevel</code> settings): we need to access our plugin configuration, so we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getPluginConf-pluginName-caller getPluginConf].
* retrieve the autohost access level of the user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getUserAccessLevel-user getUserAccessLevel]
* send a message to the battle lobby when we kick someone: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#sayBattle-message sayBattle].
* send a [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#KICKFROMBATTLE:client KICKFROMBATTLE] lobby command to kick a user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#queueLobbyCommand-lobbyCommand queueLobbyCommand].

Here is a commented implementation example of this <code>hLobbySaidBattle</code> handler, which will kick any non-privileged user saying a forbidden word in the battle lobby:
<syntaxhighlight lang="python">
# This is the handler we set up on SAIDBATTLE lobby command.
# It is called each time a player says something in the battle lobby.
sub hLobbySaidBattle {

# $command is the lobby command name (SAIDBATTLE)
# $user is the name of the user who said something in the battle lobby
# $message is the message said in the battle lobby
my ($command,$user,$message)=@_;

# First we check it's not a message from SPADS (so we don't kick ourself)
my $p_spadsConf=getSpadsConf();
return if($user eq $p_spadsConf->{lobbyLogin});

# Then we check the user isn't a privileged user
# (autohost access level >= immuneLevel)
my $p_conf=getPluginConf();
return if(getUserAccessLevel($user) >= $p_conf->{immuneLevel});

# We put the forbidden words in a array
my @forbiddenWords=split(/;/,$p_conf->{words});

# We test each forbidden word
foreach my $forbiddenWord (@forbiddenWords) {

# If the message contains the forbidden word (case insensitive)
if($message =~ /\b$forbiddenWord\b/i) {

# Then we kick the user from the battle lobby
sayBattle("Kicking $user from battle (watch your language!)");
queueLobbyCommand(["KICKFROMBATTLE",$user]);

# We quit the foreach loop (no need to test other forbidden word)
last;

}

}

}
</syntaxhighlight>
Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/forbiddenwords.py this fully functional ForbiddenWords] plugin and [http://planetspads.free.fr/spads/plugins/tutorials/ForbiddenWords.conf its associated configuration file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the associated configuration file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: <code>!plugin ForbiddenWords load</code>. And finally, as an unprivileged user we can try to say some forbidden words in the battle lobby and we should get kicked by the plugin.

 

= New-command plugin tutorial (TimePlugin) =

In this section we are going to write a plugin which implements a new command for SPADS. Such plugins are configurable plugins like the one we wrote just before, with 2 additional files to configure the new commands. This plugin will give current time when someone types "!time".

== Preparing the template ==

This time we need to download 4 files to prepare our plugin: [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPlugin.pm the new-command plugin template], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPlugin.conf the associated configuration file example], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginHelp.dat the help file example] and [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginCmd.conf the commands rights configuration file example].

As usual, we rename these files to match our plugin name: "MyNewCommandPlugin" --> "TimePlugin". Then we edit the plugin template TimePlugin.pm and replace "MyNewCommandPlugin" by "TimePlugin" in the source code, and we do the same for the plugin configuration template TimePlugin.conf, so that the "commandsFile" and "helpFile" settings are consistent with the files we just renamed.

Then we can edit our command rights requirements configuration file: TimePluginCmd.conf. This file uses the same syntax as the standard SPADS commands.conf file. The template provides a default command "myCommand" with no requirement. We will just rename this command to "time":
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# Anyone can call our command from anywhere
[time]
::|0:
|}
Now we need to write the help information for our new command. This is done in the file TimePluginHelp.dat. This file uses the same syntax as the standard SPADS help.dat file, and the template provides a help example for a command "myCommand" as a syntax reminder. After each command declaration, the first line is the command syntax description, and the other lines are optional usage examples. Let's replace this help example with our own help information for our basic !time command:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
[time]
<nowiki>!</nowiki>time - This command just prints current time
|}
== Writing plugin code ==

The new-command plugin template that we used to initialize our plugin already defines a new command named "myCommand", so all we have to do is to edit our plugin file ( TimePlugin.pm ) and replace this command by our own "time" command:

First, let's modify the code which sets up the new SPADS command handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addSpadsCommandHandler-handlers-replace-0 addSpadsCommandHandler]. This call is located in the plugin constructor. We edit it so that it becomes:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
[...]
# We declare our new command and the associated handler
addSpadsCommandHandler({time => \&hSpadsTime});
[...]
|}
We must modify the same way the code which removes this SPADS handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#removeSpadsCommandHandler-commands removeSpadsCommandHandler] in the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
[...]
# We remove our new command handler
removeSpadsCommandHandler(['time']);
[...]
|}
Finally, we must replace the handler example "hMyCommand" by our own handler "hSpadsTime". In order to answer to the user issuing the command, we can use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#answer-message answer], which will send an answer message to the user in the same way he sent the command (private message, battle lobby...).

Here is an implementation example for this basic command:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# This is the handler for our new command
sub hSpadsTime {
my ($source,$user,$p_params,$checkOnly)=@_;

# time is a basic command, we have nothing to check in case of callvote
return 1 if($checkOnly);

my @time = localtime();
@time = map(sprintf("%02d",$_),@time);

answer("Current local time: $time[2]:$time[1]:$time[0]");
}
|}

Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/TimePlugin.pm this fully functional TimePlugin] plugin, and its associated [http://planetspads.free.fr/spads/plugins/tutorials/TimePlugin.conf configuration file], [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginCmd.conf command rights configuration file] and [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginHelp.dat command help file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module and the plugin help file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the 2 configuration files in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: "!plugin TimePlugin load". And finally, we can try to say !time in a private message to SPADS or in the battle lobby, and SPADS should answer giving current local time. Our !time command help should also appear in "!help" and "!help time" outputs.

[[Category:SPADS]]

SPADS plugin development

2021-01-28T09:57:16Z

Bibim: /* Configurable plugin tutorial (ForbiddenWords) */

= Introduction =

SPADS is an autohost system coded in Perl, it supports both Perl and Python plugins. This tutorial deals with Perl plugin development only (for Python plugin development another tutorial is available [https://springrts.com/wiki/SPADS_plugin_development_(Python) here]).

SPADS plugins are object-oriented modules. It is strongly recommended to already know Perl basics before starting Perl plugin development (a brief introduction to Perl is available [https://perldoc.perl.org/perlintro here]).

 
= 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 [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] (the <code>.py</code> files must be ignored for this tutorial, these are the Python versions of the templates).

Our first plugin will be very basic, so we will use the simplest template: <code>MySimplePlugin.pm</code>. 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 <code>HelloWorld</code>. We have to rename the downloaded template from <code>MySimplePlugin.pm</code> to <code>HelloWorld.pm</code>, and edit it to replace <code>MySimplePlugin</code> by <code>HelloWorld</code> 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 <code>spads.conf</code> configuration file and reload SPADS configuration).

We have to move our new plugin (<code>HelloWorld.pm</code>) 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): <code>!plugin HelloWorld load</code>. SPADS should answer <code>Loaded plugin HelloWorld.</code>, 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-self-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 <code>onPrivateMsg</code> callback, which will answer <code>Hello World</code> to anyone saying <code>Hello</code> in a private message to SPADS:
<syntaxhighlight lang="perl">
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;

}</syntaxhighlight>

All we have to do now is adding this callback declaration in our <code>HelloWorld.pm</code> 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: <code>!plugin HelloWorld reload</code>. SPADS should answer <code>Reloaded plugin HelloWorld.</code>, which indicates the plugin has been reloaded successfully.

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

 
= Configurable plugin tutorial (ForbiddenWords) =

In this section we are going to write our first configurable SPADS plugin (a configurable plugin has its own configuration file, named after the plugin name but with <code>.conf</code> extension). This plugin will monitor all messages said by players in the battle lobby, and will kick players who use swear words.

== Specifying our configuration parameters ==

The first step of writing a configurable plugin is to choose how we will configure it. In our example, we will use 2 configuration parameters: <code>words</code> will contain the list of forbidden words, and <code>immuneLevel</code> will contain the minimum autohost access level to be immune regarding these forbidden words checks.

We choose to make <code>words</code> a global setting (unmodifiable, not impacted by preset change), and <code>immuneLevel</code> a preset setting (modifiable, can be impacted by preset change). The <code>words</code> global setting will have no restriction (can be empty, can contain any character...), whereas the <code>immuneLevel</code> preset setting will only be allowed to be an integer or integer range.

== Preparing the template ==

Once we have a clear view of our configuration settings, we can start adapting the template for our needs. Since we are making a configurable plugin, this time we will download [http://planetspads.free.fr/spads/plugins/templates/commented/MyConfigurablePlugin.pm the configurable plugin template] and its associated [http://planetspads.free.fr/spads/plugins/templates/commented/MyConfigurablePlugin.conf configuration file example].

First, let's take a look at the configuration file example. This is a just a basic configuration file containing one global setting example and one preset setting example. Let's modify this file to match the configuration we chose as follows (don't forget to rename the file from <code>MyConfigurablePlugin.conf</code> to <code>ForbiddenWords.conf</code> also):
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# This is our global setting (can't be changed without reloading the configuration)
words:ass;asshole;bastard;bitch;cunt;fuck;motherfucker;shit;whore

# We must define our preset setting in the default preset at least
[default]

# This is our preset setting, which can be changed with "!plugin ... set ..."
# or by loading a preset.
# "100" is the default value, and any integer between 0 and 140 is allowed
immuneLevel:100|0-140
|}
Then we must prepare the plugin template itself, by renaming it from <code>MyConfigurablePlugin.pm</code> to <code>ForbiddenWords.pm</code> and editing it to replace <code>MyConfigurablePlugin</code> by <code>ForbiddenWords</code> in the source code. We must also adapt the template so that it uses the configuration settings we chose. This is done by modifying the <code>%globalPluginParams</code> and <code>%presetPluginParam</code> declarations as follows:
<syntaxhighlight lang="perl">
# We define one global setting "words" and one preset setting "immuneLevel".
# "words" has no type associated (no restriction on allowed values)
# "immuneLevel" must be an integer or an integer range
# (check %paramTypes hash in SpadsConf.pm for a complete list of allowed
# setting types)
my %globalPluginParams = ( words => [] );
my %presetPluginParams = ( immuneLevel => ['integer','integerRange'] );
</syntaxhighlight>

== Writing plugin code ==

We want our plugin to react to messages said in the battle lobby. There is no dedicated callback for this event in [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html SPADS plugin API documentation], so we have to set up our own handler on the [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#SAIDBATTLE:server SAIDBATTLE lobby command]. To do so we have to call the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addLobbyCommandHandler-handlers-priority-caller addLobbyCommandHandler]. We will call this function at the end of our plugin constructor as follows, so that it will be set up directly when the plugin is loaded:
<syntaxhighlight lang="perl">
[...]

# We set up a lobby command handler on SAIDBATTLE
addLobbyCommandHandler({SAIDBATTLE => \&hLobbySaidBattle});

# We return the instantiated plugin
return $self;

}
</syntaxhighlight>
However, if SPADS is disconnected from the lobby due to network problems for example, all lobby handlers are automatically removed. So we must re-add them each time we connect to lobby server. This can be done using the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onLobbyConnected-self-lobbyInterface onLobbyConnected] event-based callback as follows:
<syntaxhighlight lang="perl">
# This callback is called each time we (re)connect to the lobby server
sub onLobbyConnected {

# When we are disconnected from the lobby server, all lobby command
# handlers are automatically removed, so we (re)set up our command
# handler here.
addLobbyCommandHandler({SAIDBATTLE => \&hLobbySaidBattle});

}
</syntaxhighlight>
Also, it is a good practice to remove any handler we have added when the plugin is unloaded. To do so we must implement the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback as follows:
<syntaxhighlight lang="perl">
# This callback is called when the plugin is unloaded
sub onUnload {

# We remove our lobby command handler when the plugin is unloaded
removeLobbyCommandHandler(['SAIDBATTLE']);

}
</syntaxhighlight>
Finally, we have to implement our <code>SAIDBATTLE</code> handler <code>hLobbySaidBattle</code>. In this handler we need to perform following operations:
* skip processing if the user is the autohost itself: we need to access SPADS configuration to compare the user name with the [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:lobbyLogin lobbyLogin] setting value. So we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getSpadsConf getSpadsConf].
* perform processing according to our configuration (<code>words</code> and <code>immuneLevel</code> settings): we need to access our plugin configuration, so we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getPluginConf-pluginName-caller getPluginConf].
* retrieve the autohost access level of the user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getUserAccessLevel-user getUserAccessLevel]
* send a message to the battle lobby when we kick someone: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#sayBattle-message sayBattle].
* send a [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#KICKFROMBATTLE:client KICKFROMBATTLE] lobby command to kick a user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#queueLobbyCommand-lobbyCommand queueLobbyCommand].

Here is a commented implementation example of this <code>hLobbySaidBattle</code> handler, which will kick any non-privileged user saying a forbidden word in the battle lobby:
<syntaxhighlight lang="perl">
# This is the handler we set up on SAIDBATTLE lobby command.
# It is called each time a player says something in the battle lobby.
sub hLobbySaidBattle {

# $command is the lobby command name (SAIDBATTLE)
# $user is the name of the user who said something in the battle lobby
# $message is the message said in the battle lobby
my ($command,$user,$message)=@_;

# First we check it's not a message from SPADS (so we don't kick ourself)
my $p_spadsConf=getSpadsConf();
return if($user eq $p_spadsConf->{lobbyLogin});

# Then we check the user isn't a privileged user
# (autohost access level >= immuneLevel)
my $p_conf=getPluginConf();
return if(getUserAccessLevel($user) >= $p_conf->{immuneLevel});

# We put the forbidden words in a array
my @forbiddenWords=split(/;/,$p_conf->{words});

# We test each forbidden word
foreach my $forbiddenWord (@forbiddenWords) {

# If the message contains the forbidden word (case insensitive)
if($message =~ /\b$forbiddenWord\b/i) {

# Then we kick the user from the battle lobby
sayBattle("Kicking $user from battle (watch your language!)");
queueLobbyCommand(["KICKFROMBATTLE",$user]);

# We quit the foreach loop (no need to test other forbidden word)
last;

}

}

}
</syntaxhighlight>
Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/ForbiddenWords.pm this fully functional ForbiddenWords] plugin and [http://planetspads.free.fr/spads/plugins/tutorials/ForbiddenWords.conf its associated configuration file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the associated configuration file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: <code>!plugin ForbiddenWords load</code>. And finally, as an unprivileged user we can try to say some forbidden words in the battle lobby and we should get kicked by the plugin.

 

= New-command plugin tutorial (TimePlugin) =

In this section we are going to write a plugin which implements a new command for SPADS. Such plugins are configurable plugins like the one we wrote just before, with 2 additional files to configure the new commands. This plugin will give current time when someone types "!time".

== Preparing the template ==

This time we need to download 4 files to prepare our plugin: [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPlugin.pm the new-command plugin template], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPlugin.conf the associated configuration file example], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginHelp.dat the help file example] and [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginCmd.conf the commands rights configuration file example].

As usual, we rename these files to match our plugin name: "MyNewCommandPlugin" --> "TimePlugin". Then we edit the plugin template TimePlugin.pm and replace "MyNewCommandPlugin" by "TimePlugin" in the source code, and we do the same for the plugin configuration template TimePlugin.conf, so that the "commandsFile" and "helpFile" settings are consistent with the files we just renamed.

Then we can edit our command rights requirements configuration file: TimePluginCmd.conf. This file uses the same syntax as the standard SPADS commands.conf file. The template provides a default command "myCommand" with no requirement. We will just rename this command to "time":
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# Anyone can call our command from anywhere
[time]
::|0:
|}
Now we need to write the help information for our new command. This is done in the file TimePluginHelp.dat. This file uses the same syntax as the standard SPADS help.dat file, and the template provides a help example for a command "myCommand" as a syntax reminder. After each command declaration, the first line is the command syntax description, and the other lines are optional usage examples. Let's replace this help example with our own help information for our basic !time command:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
[time]
<nowiki>!</nowiki>time - This command just prints current time
|}
== Writing plugin code ==

The new-command plugin template that we used to initialize our plugin already defines a new command named "myCommand", so all we have to do is to edit our plugin file ( TimePlugin.pm ) and replace this command by our own "time" command:

First, let's modify the code which sets up the new SPADS command handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addSpadsCommandHandler-handlers-replace-0 addSpadsCommandHandler]. This call is located in the plugin constructor. We edit it so that it becomes:
<syntaxhighlight lang="perl">
[...]
# We declare our new command and the associated handler
addSpadsCommandHandler({time => \&hSpadsTime});
[...]
</syntaxhighlight>
We must modify the same way the code which removes this SPADS handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#removeSpadsCommandHandler-commands removeSpadsCommandHandler] in the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback:
<syntaxhighlight lang="perl">
[...]
# We remove our new command handler
removeSpadsCommandHandler(['time']);
[...]
</syntaxhighlight>
Finally, we must replace the handler example "hMyCommand" by our own handler "hSpadsTime". In order to answer to the user issuing the command, we can use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#answer-message answer], which will send an answer message to the user in the same way he sent the command (private message, battle lobby...).

Here is an implementation example for this basic command:
<syntaxhighlight lang="perl">
# This is the handler for our new command
sub hSpadsTime {
my ($source,$user,$p_params,$checkOnly)=@_;

# time is a basic command, we have nothing to check in case of callvote
return 1 if($checkOnly);

my @time = localtime();
@time = map(sprintf("%02d",$_),@time);

answer("Current local time: $time[2]:$time[1]:$time[0]");
}
</syntaxhighlight>

Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/TimePlugin.pm this fully functional TimePlugin] plugin, and its associated [http://planetspads.free.fr/spads/plugins/tutorials/TimePlugin.conf configuration file], [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginCmd.conf command rights configuration file] and [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginHelp.dat command help file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module and the plugin help file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the 2 configuration files in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: "!plugin TimePlugin load". And finally, we can try to say !time in a private message to SPADS or in the battle lobby, and SPADS should answer giving current local time. Our !time command help should also appear in "!help" and "!help time" outputs.

[[Category:SPADS]]

SPADS Inline::Python installation guide

2021-01-28T09:27:00Z

Bibim: /* Step 2: Using cpanminus to install Inline::Python */

= Introduction =

<code>Inline::Python</code> is a Perl module which allows interactions between Perl code and Python code. SPADS uses it to communicate with plugins coded in Python.

Unfortunately the current stable release of this module suffers from a bug which makes Perl strings appear as byte strings when used with Python 3 (Python 2 is unaffected). This is not a blocking problem, as Python can easily convert these data if needed and SPADS plugin API offers dedicated functions to deal with the problem (cf the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#Perl-strings-conversions PYTHON SPECIFIC NOTES - Perl strings conversions] section of the Plugin API documentation). However, a cleaner way to solve this problem is to install a fixed version of the module, directly from the official module maintainer repository. The remaining of this document will detail the different ways to install <code>Inline::Python</code>, on Linux and Windows.

 
= Installing Inline::Python on Linux =
 
== Method 1: Using cpanminus to install latest version from GitHub ==
<code>cpanminus</code> is a lightweight package manager for Perl, which is able to install Perl modules directly from Git repositories. This is very useful for <code>Inline::Python</code> installation because only the latest version from the module maintainer repository includes the fix for Perl string conversions with Python 3.

The first step consists in installing <code>cpanminus</code> (if not already installed on your system). To do that you can usually use the package manager of your Linux distribution. For example, for Debian based distributions: <code>apt-get install cpanminus</code>, or for Red Hat based distributions: <code>dnf install perl-App-cpanminus</code> (for other cases, check [https://metacpan.org/pod/App::cpanminus#INSTALLATION the INSTALLATION section of cpanminus documentation]).

Once <code>cpanminus</code> is installed, it can be used to install the latest version of <code>Inline::Python</code> from module maintainer's repository. This can be done simply by entering following command (with root privileges if you are using the system Perl): 
<code><nowiki>cpanm https://github.com/niner/inline-python-pm.git</nowiki></code>

 
== Method 2: Using the package manager of your Linux distribution ==
This is the easiest way to install <code>Inline::Python</code> (if your distribution supports it), as it automatically downloads and installs a package specifically prepared for your distribution. However, this method installs the stable release of <code>Inline::Python</code>, which suffers from the string conversion bug with Python 3 explained in introduction. So this method is only recommended if you don't plan to use Python 3 or if the installation method based on <code>cpanminus</code> failed.

For this method you just need to find the name of the system package containing the <code>Inline::Python</code> Perl module and install it on your system. 
For example, for Debian based distributions: <code>apt-get install libinline-python-perl</code> 
For Red Hat based distributions: <code>dnf install perl-Inline-Python</code>

 
== Method 3: Using cpan ==
<code>cpan</code> is the standard tool included with Perl to install modules from the [https://www.cpan.org/ Comprehensive Perl Archive Network]. Unfortunately, only the current stable releases of the modules can easily be installed this way, so this method should only be reserved to cases where all other installation methods failed.

To install <code>Inline::Python</code> using <code>cpan</code>, simply enter following command (with root privileges if you are using the system Perl): 
<code>cpan Inline::Python</code>

 
= Installing Inline::Python on Windows =
 
== Step 1: Installing cpanminus ==
<code>cpanminus</code> is a lightweight module manager for Perl, which is able to install Perl modules directly from Git repositories and allows interactive mode installations.

If your are using Strawberry Perl, <code>cpanminus</code> should be pre-installed (you can check it by trying the <code>cpanm</code> command in a console windows). If you are using another Perl distribution and <code>cpanminus</code> isn't pre-installed, you should be able to use the packet manager of your Perl distribution (<code>ppm</code> for example for old ActiveState Perl releases) to install <code>cpanminus</code>. You can also use the generic default Perl module manager <code>cpan</code> to install it using following command: <code>cpan cpanminus</code>

 
== Step 2: Using cpanminus to install Inline::Python ==
As explained in introduction, the current stable release of <code>Inline::Python</code> suffers from the string conversion bug with Python 3, so it is recommended to install the latest version instead. Unfortunately, the installation script included in the latest version on the module maintainer repository has some problems when installing on Windows. I created my own fork on GitHub to fix these installation problems. As long as the module maintainer didn't merge my fixes in his repository, I recommend using my fork to install the latest version of <code>Inline::Python</code> on Windows, using following command: 
<code><nowiki>cpanm https://github.com/Yaribz/inline-python-pm.git</nowiki></code>

 
If for some reason the installation of the latest version of <code>Inline::Python</code> fails, you can try to install the stable release instead. Unfortunately, the current stable release of <code>Inline::Python</code> doesn't install automatically on Windows due to broken Python installation detection and one test which is coded for Linux system only and which must be skipped. Consequently, <code>cpanminus</code> must be run in interactive mode and with a flag to force installation despite the failing test, using this command: 
<code>cpanm --interactive -f Inline::Python</code>

The install script will then ask 4 questions:
# <code>Use which? [1]</code> Here you must enter the full path of your <code>python.exe</code> file from your Python installation (warning: paths containing spaces are not supported by the installer). For example: <code>C:\Python\python.exe</code>
# <code>Enter extra libraries (e.g. -lfoo -lbar) [None]</code> Here you can press enter, as no additional library should be needed for standard Python installation.
# <code>Which? Or enter another. [1]</code> Here you need to enter the digit corresponding to the library with 2 digits in its name. For example: <code>2</code> (to select entry <code>2) C:/Python/libs/python39.lib</code>)
# <code>Which? Or enter another. [1]</code> Here you can press enter as the install script should have auto-detected the include location of your Python installation correctly.

SPADS Inline::Python installation guide

2021-01-28T09:25:37Z

Bibim: /* Step 2: Using cpanminus to install Inline::Python */

= Introduction =

<code>Inline::Python</code> is a Perl module which allows interactions between Perl code and Python code. SPADS uses it to communicate with plugins coded in Python.

Unfortunately the current stable release of this module suffers from a bug which makes Perl strings appear as byte strings when used with Python 3 (Python 2 is unaffected). This is not a blocking problem, as Python can easily convert these data if needed and SPADS plugin API offers dedicated functions to deal with the problem (cf the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#Perl-strings-conversions PYTHON SPECIFIC NOTES - Perl strings conversions] section of the Plugin API documentation). However, a cleaner way to solve this problem is to install a fixed version of the module, directly from the official module maintainer repository. The remaining of this document will detail the different ways to install <code>Inline::Python</code>, on Linux and Windows.

 
= Installing Inline::Python on Linux =
 
== Method 1: Using cpanminus to install latest version from GitHub ==
<code>cpanminus</code> is a lightweight package manager for Perl, which is able to install Perl modules directly from Git repositories. This is very useful for <code>Inline::Python</code> installation because only the latest version from the module maintainer repository includes the fix for Perl string conversions with Python 3.

The first step consists in installing <code>cpanminus</code> (if not already installed on your system). To do that you can usually use the package manager of your Linux distribution. For example, for Debian based distributions: <code>apt-get install cpanminus</code>, or for Red Hat based distributions: <code>dnf install perl-App-cpanminus</code> (for other cases, check [https://metacpan.org/pod/App::cpanminus#INSTALLATION the INSTALLATION section of cpanminus documentation]).

Once <code>cpanminus</code> is installed, it can be used to install the latest version of <code>Inline::Python</code> from module maintainer's repository. This can be done simply by entering following command (with root privileges if you are using the system Perl): 
<code><nowiki>cpanm https://github.com/niner/inline-python-pm.git</nowiki></code>

 
== Method 2: Using the package manager of your Linux distribution ==
This is the easiest way to install <code>Inline::Python</code> (if your distribution supports it), as it automatically downloads and installs a package specifically prepared for your distribution. However, this method installs the stable release of <code>Inline::Python</code>, which suffers from the string conversion bug with Python 3 explained in introduction. So this method is only recommended if you don't plan to use Python 3 or if the installation method based on <code>cpanminus</code> failed.

For this method you just need to find the name of the system package containing the <code>Inline::Python</code> Perl module and install it on your system. 
For example, for Debian based distributions: <code>apt-get install libinline-python-perl</code> 
For Red Hat based distributions: <code>dnf install perl-Inline-Python</code>

 
== Method 3: Using cpan ==
<code>cpan</code> is the standard tool included with Perl to install modules from the [https://www.cpan.org/ Comprehensive Perl Archive Network]. Unfortunately, only the current stable releases of the modules can easily be installed this way, so this method should only be reserved to cases where all other installation methods failed.

To install <code>Inline::Python</code> using <code>cpan</code>, simply enter following command (with root privileges if you are using the system Perl): 
<code>cpan Inline::Python</code>

 
= Installing Inline::Python on Windows =
 
== Step 1: Installing cpanminus ==
<code>cpanminus</code> is a lightweight module manager for Perl, which is able to install Perl modules directly from Git repositories and allows interactive mode installations.

If your are using Strawberry Perl, <code>cpanminus</code> should be pre-installed (you can check it by trying the <code>cpanm</code> command in a console windows). If you are using another Perl distribution and <code>cpanminus</code> isn't pre-installed, you should be able to use the packet manager of your Perl distribution (<code>ppm</code> for example for old ActiveState Perl releases) to install <code>cpanminus</code>. You can also use the generic default Perl module manager <code>cpan</code> to install it using following command: <code>cpan cpanminus</code>

 
== Step 2: Using cpanminus to install Inline::Python ==
As explained in introduction, the current stable release of <code>Inline::Python</code> suffers from the string conversion bug with Python 3, so it is recommended to install the latest version instead. Unfortunately, the installation script included in the latest version on the module maintainer repository has some problems when installing on Windows. I created my own fork on GitHub to fix these installation problems. As long as the module maintainer didn't merge my fixes in his repository, I recommend using my fork to install the latest version of <code>Inline::Python</code> on Windows, using following command: 
<code><nowiki>cpanm https://github.com/Yaribz/inline-python-pm.git</nowiki></code>

 
If for some reason the installation from my fork fails, you can try to install the stable release of <code>Inline::Python</code> instead. Unfortunately, the current stable release of <code>Inline::Python</code> doesn't install automatically on Windows due to broken Python installation detection and one test which is coded for Linux system only and which must be skipped. Consequently, <code>cpanminus</code> must be run in interactive mode and with a flag to force installation despite the failing test, using this command: 
<code>cpanm --interactive -f Inline::Python</code>

The install script will then ask 4 questions:
# <code>Use which? [1]</code> Here you must enter the full path of your <code>python.exe</code> file from your Python installation (warning: paths containing spaces are not supported by the installer). For example: <code>C:\Python\python.exe</code>
# <code>Enter extra libraries (e.g. -lfoo -lbar) [None]</code> Here you can press enter, as no additional library should be needed for standard Python installation.
# <code>Which? Or enter another. [1]</code> Here you need to enter the digit corresponding to the library with 2 digits in its name. For example: <code>2</code> (to select entry <code>2) C:/Python/libs/python39.lib</code>)
# <code>Which? Or enter another. [1]</code> Here you can press enter as the install script should have auto-detected the include location of your Python installation correctly.

SPADS Inline::Python installation guide

2021-01-28T09:19:22Z

Bibim:

= Introduction =

<code>Inline::Python</code> is a Perl module which allows interactions between Perl code and Python code. SPADS uses it to communicate with plugins coded in Python.

Unfortunately the current stable release of this module suffers from a bug which makes Perl strings appear as byte strings when used with Python 3 (Python 2 is unaffected). This is not a blocking problem, as Python can easily convert these data if needed and SPADS plugin API offers dedicated functions to deal with the problem (cf the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#Perl-strings-conversions PYTHON SPECIFIC NOTES - Perl strings conversions] section of the Plugin API documentation). However, a cleaner way to solve this problem is to install a fixed version of the module, directly from the official module maintainer repository. The remaining of this document will detail the different ways to install <code>Inline::Python</code>, on Linux and Windows.

 
= Installing Inline::Python on Linux =
 
== Method 1: Using cpanminus to install latest version from GitHub ==
<code>cpanminus</code> is a lightweight package manager for Perl, which is able to install Perl modules directly from Git repositories. This is very useful for <code>Inline::Python</code> installation because only the latest version from the module maintainer repository includes the fix for Perl string conversions with Python 3.

The first step consists in installing <code>cpanminus</code> (if not already installed on your system). To do that you can usually use the package manager of your Linux distribution. For example, for Debian based distributions: <code>apt-get install cpanminus</code>, or for Red Hat based distributions: <code>dnf install perl-App-cpanminus</code> (for other cases, check [https://metacpan.org/pod/App::cpanminus#INSTALLATION the INSTALLATION section of cpanminus documentation]).

Once <code>cpanminus</code> is installed, it can be used to install the latest version of <code>Inline::Python</code> from module maintainer's repository. This can be done simply by entering following command (with root privileges if you are using the system Perl): 
<code><nowiki>cpanm https://github.com/niner/inline-python-pm.git</nowiki></code>

 
== Method 2: Using the package manager of your Linux distribution ==
This is the easiest way to install <code>Inline::Python</code> (if your distribution supports it), as it automatically downloads and installs a package specifically prepared for your distribution. However, this method installs the stable release of <code>Inline::Python</code>, which suffers from the string conversion bug with Python 3 explained in introduction. So this method is only recommended if you don't plan to use Python 3 or if the installation method based on <code>cpanminus</code> failed.

For this method you just need to find the name of the system package containing the <code>Inline::Python</code> Perl module and install it on your system. 
For example, for Debian based distributions: <code>apt-get install libinline-python-perl</code> 
For Red Hat based distributions: <code>dnf install perl-Inline-Python</code>

 
== Method 3: Using cpan ==
<code>cpan</code> is the standard tool included with Perl to install modules from the [https://www.cpan.org/ Comprehensive Perl Archive Network]. Unfortunately, only the current stable releases of the modules can easily be installed this way, so this method should only be reserved to cases where all other installation methods failed.

To install <code>Inline::Python</code> using <code>cpan</code>, simply enter following command (with root privileges if you are using the system Perl): 
<code>cpan Inline::Python</code>

 
= Installing Inline::Python on Windows =
 
== Step 1: Installing cpanminus ==
<code>cpanminus</code> is a lightweight module manager for Perl, which is able to install Perl modules directly from Git repositories and allows interactive mode installations.

If your are using Strawberry Perl, <code>cpanminus</code> should be pre-installed (you can check it by trying the <code>cpanm</code> command in a console windows). If you are using another Perl distribution and <code>cpanminus</code> isn't pre-installed, you should be able to use the packet manager of your Perl distribution (<code>ppm</code> for example for old ActiveState Perl releases) to install <code>cpanminus</code>. You can also use the generic default Perl module manager <code>cpan</code> to install it using following command: <code>cpan cpanminus</code>

 
== Step 2: Using cpanminus to install Inline::Python ==
As explained in introduction, the current stable release of <code>Inline::Python</code> suffers from the string conversion bug with Python 3, so it is recommended to install the latest version instead. Unfortunately, the installation script included in the latest version on the module maintainer repository has some problems when installing on Windows. I created my own fork on GitHub to fix these installation problems. As long as the module maintainer didn't merge my fixes in his repository, I recommend using my fork to install the latest version of <code>Inline::Python</code> on Windows, using following command: 
<code><nowiki>cpanm https://github.com/Yaribz/inline-python-pm.git</nowiki></code>

 
If for some reason the installation from my fork fails, you can try to install the stable release of <code>Inline::Python</code> instead. Unfortunately, the current stable release of <code>Inline::Python</code> doesn't install automatically on Windows due to broken Python libraries detection and one test which is coded for Linux system only and which must be skipped. Consequently, <code>cpanminus</code> must be run in interactive mode and with a flag to force installation despite the failing test, using this command: 
<code>cpanm --interactive -f Inline::Python</code>

The install script will then ask 4 questions:
# <code>Use which? [1]</code> Here you must enter the full path of your <code>python.exe</code> file from your Python installation (warning: paths containing spaces are not supported by the installer). For example: <code>C:\Python\python.exe</code>
# <code>Enter extra libraries (e.g. -lfoo -lbar) [None]</code> Here you can press enter, as no additional library should be needed for standard Python installation.
# <code>Which? Or enter another. [1]</code> Here you need to enter the digit corresponding to the library with 2 digits in its name. For example: <code>2</code> (to select entry <code>2) C:/Python/libs/python39.lib</code>)
# <code>Which? Or enter another. [1]</code> Here you can press enter as the install script should have auto-detected the include location of your Python installation correctly.

SPADS Inline::Python installation guide

2021-01-28T09:04:26Z

Bibim: /* Installing Inline::Python on Windows */

= Introduction =

<code>Inline::Python</code> is a Perl module which allows interactions between Perl code and Python code. SPADS uses it to communicate with plugins coded in Python.

Unfortunately the current stable release of this module suffers from a bug which makes Perl strings appear as byte strings when used with Python 3 (Python 2 is unaffected). This is not a blocking problem, as Python can easily convert these data if needed and SPADS plugin API offers dedicated functions to deal with the problem (cf the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#Perl-strings-conversions PYTHON SPECIFIC NOTES - Perl strings conversions] section of the Plugin API documentation). However, a cleaner way to solve this problem is to install a fixed version of the module, directly from the official module maintainer repository. The remaining of this document will detail the different ways to install <code>Inline::Python</code>, on Linux and Windows.

 
= Installing Inline::Python on Linux =
 
== Method 1: Using cpanminus to install latest version from GitHub ==
<code>cpanminus</code> is a lightweight package manager for Perl, which is able to install Perl modules directly from Git repositories. This is very useful for <code>Inline::Python</code> installation because only the latest version from the module maintainer repository includes the fix for Perl string conversions with Python 3.

The first step consists in installing <code>cpanminus</code> (if not already installed on your system). To do that you can usually use the package manager of your Linux distribution. For example, for Debian based distributions: <code>apt-get install cpanminus</code>, or for Red Hat based distributions: <code>dnf install perl-App-cpanminus</code> (for other cases, check [https://metacpan.org/pod/App::cpanminus#INSTALLATION the INSTALLATION section of cpanminus documentation]).

Once <code>cpanminus</code> is installed, it can be used to install the latest version of <code>Inline::Python</code> from module maintainer's repository. This can be done simply by entering following command (with root privileges if you are using the system Perl): 
<code><nowiki>cpanm https://github.com/niner/inline-python-pm.git</nowiki></code>

 
== Method 2: Using the package manager of your Linux distribution ==
This is the easiest way to install <code>Inline::Python</code> (if your distribution supports it), as it automatically downloads and installs a package specifically prepared for your distribution. However, this method installs the stable release of <code>Inline::Python</code>, which suffers from the string conversion bug with Python 3 explained in introduction. So this method is only recommended if you don't plan to use Python 3 or if the installation method based on <code>cpanminus</code> failed.

For this method you just need to find the name of the system package containing the <code>Inline::Python</code> Perl module and install it on your system. 
For example, for Debian based distributions: <code>apt-get install libinline-python-perl</code> 
For Red Hat based distributions: <code>dnf install perl-Inline-Python</code>

 
== Method 3: Using cpan ==
<code>cpan</code> is the standard tool included with Perl to install modules from the [https://www.cpan.org/ Comprehensive Perl Archive Network]. Unfortunately, only the current stable releases of the modules can easily be installed this way, so this method should only be reserved to cases where all other installation methods failed.

To install <code>Inline::Python</code> using <code>cpan</code>, simply enter following command (with root privileges if you are using the system Perl): 
<code>cpan Inline::Python</code>

 
= Installing Inline::Python on Windows =
 
== Step 1: Installing cpanminus ==
<code>cpanminus</code> is a lightweight module manager for Perl, which is able to install Perl modules directly from Git repositories and allows interactive mode installations.

If your are using Strawberry Perl, <code>cpanminus</code> should be pre-installed (you can check it by trying the <code>cpanm</code> command in a console windows). If you are using another Perl distribution and <code>cpanminus</code> isn't pre-installed, you should be able to use the packet manager of your Perl distribution (<code>ppm</code> for example for old ActiveState Perl releases) to install <code>cpanminus</code>. You can also use the generic default Perl module manager <code>cpan</code> to install it using following command: <code>cpan cpanminus</code>

 
== Step 2: Using cpanminus to install Inline::Python ==
As explained in introduction, the current stable release of <code>Inline::Python</code> suffers from the string conversion bug with Python 3, so it is recommended to install the latest version instead. Unfortunately, the installation script included in the latest version on the module maintainer repository has some problems when installing on Windows. I created my own fork on GitHub to fix these installation problems. As long as the module maintainer didn't merge my fixes in his repository, I recommend using my fork to install the latest version of <code>Inline::Python</code> on Windows, using following command: 
<code><nowiki>cpanm https://github.com/Yaribz/inline-python-pm.git</nowiki></code>

 
If for some reason the installation from my fork fails, you can try to install the stable release of <code>Inline::Python</code> instead. Unfortunately, the current stable release of <code>Inline::Python</code> doesn't install automatically on Windows due to broken Python libraries detection and one test which is coded for Linux system only and which must be skipped. Consequently, <code>cpanminus</code> must be run in ineractive mode and with a flag to force installation despite the failing test, using this command: 
<code>cpanm --interactive -f Inline::Python</code>

The install script will then ask 4 questions:
# <code>Use which? [1]</code> Here you must enter the full path of your <code>python.exe</code> file from your Python installation (warning: paths containing spaces are not supported by the installer). For example: <code>C:\Python\python.exe</code>
# <code>Enter extra libraries (e.g. -lfoo -lbar) [None]</code> Here you can press enter, as no additional library should be needed for standard Python installation.
# <code>Which? Or enter another. [1]</code> Here you need to enter the digit corresponding to the library with 2 digits in its name. For example: <code>2</code> (to select entry <code>2) C:/Python/libs/python39.lib</code>)
# <code>Which? Or enter another. [1]</code> Here you can press enter as the install script should have auto-detected the include location of your Python installation correctly.

SPADS plugin development (Python)

2021-01-28T07:41:43Z

Bibim: /* Technical prerequisites */

= Introduction =

SPADS is an autohost system coded in Perl, it supports both Perl and Python plugins. This tutorial deals with Python plugin development only (for Perl plugin development another tutorial is available [https://springrts.com/wiki/SPADS_plugin_development here]).

SPADS plugins are object-oriented modules. It is strongly recommended to already know Python basics before starting Python plugin development (a Python tutorial is available [https://docs.python.org/3/tutorial/ here]).

 
= Technical prerequisites =

Python (the Python interpreter and its libraries) must be installed on the system (versions 2.6+ or 3.2+ recommended). The type of installation (32-bit / 64-bit) must be consistent with the Perl version and the Spring engine used for SPADS.

Additionally, in order to allow communication between Perl code (SPADS core) and Python code (SPADS plugins), SPADS uses a Perl module named <code>Inline::Python</code> which must also be installed on the system. It is recommended to install the latest version for SPADS, refer to [https://springrts.com/wiki/SPADS_Inline::Python_installation_guide this guide] for installation.

 

= 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 [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] (the <code>.pm</code> files must be ignored for this tutorial, these are the Perl versions of the templates).

Our first plugin will be very basic, so we will use the simplest template: <code>mysimpleplugin.py</code>. Let's download [http://planetspads.free.fr/spads/plugins/templates/commented/mysimpleplugin.py 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 <code>HelloWorld</code>. We have to rename the downloaded template from <code>mysimpleplugin.py</code> to <code>helloworld.py</code>, and edit it to replace <code>MySimplePlugin</code> by <code>HelloWorld</code> 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 <code>spads.conf</code> configuration file and reload SPADS configuration).

We have to move our new plugin (<code>helloworld.py</code>) 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): <code>!plugin HelloWorld load</code>. SPADS should answer <code>Loaded plugin HelloWorld.</code>, 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-self-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 <code>onPrivateMsg</code> callback, which will answer <code>Hello World</code> to anyone saying <code>Hello</code> in a private message to SPADS:
<syntaxhighlight lang="python">
# This is the callback called each time SPADS receives a private message
# 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
def onPrivateMsg(self,userName,message):

# Here we "fix" strings received from Perl in case
# the Inline::Python module transmits them as byte strings
(userName,message)=spads.fix_string(userName,message)

# We check the message sent by the user is "Hello"
if message == 'Hello':

# We send our wonderful Hello World message
spads.sayPrivate(userName,'Hello World')

# We return 0 because we don't want to filter out private messages
# for other SPADS processing
return 0</syntaxhighlight>

All we have to do now is adding this callback declaration in our <code>helloworld.py</code> file located in SPADS plugins directory. We obtain [http://planetspads.free.fr/spads/plugins/tutorials/helloworld.py 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: <code>!plugin HelloWorld reload</code>. SPADS should answer <code>Reloaded plugin HelloWorld.</code>, which indicates the plugin has been reloaded successfully.

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

'''/!\ WORK IN PROGRESS /!\'''

 
= Configurable plugin tutorial (ForbiddenWords) =

In this section we are going to write our first configurable SPADS plugin (a configurable plugin has its own configuration file, named after the plugin name but with ".conf" extension). This plugin will monitor all messages said by players in the battle lobby, and will kick players who use swear words.

== Specifying our configuration parameters ==

The first step of writing a configurable plugin is to choose how we will configure it. In our example, we will use 2 configuration parameters: "words" will contain the list of forbidden words, and "immuneLevel" will contain the minimum autohost access level to be immune regarding these forbidden words checks.

We choose to make "words" a global setting (unmodifiable, not impacted by preset change), and "immuneLevel" a preset setting (modifiable, can be impacted by preset change). The "words" global setting will have no restriction (can be empty, can contain any character...), whereas the "immuneLevel" preset setting will only be allowed to be an integer or integer range.

== Preparing the template ==

Once we have a clear view of our configuration settings, we can start adapting the template for our needs. Since we are making a configurable plugin, this time we will download [http://planetspads.free.fr/spads/plugins/templates/commented/MyConfigurablePlugin.pm the configurable plugin template] and its associated [http://planetspads.free.fr/spads/plugins/templates/commented/MyConfigurablePlugin.conf configuration file example].

First, let's take a look at the configuration file example. This is a just a basic configuration file containing one global setting example and one preset setting example. Let's modify this file to match the configuration we chose as follows (don't forget to rename the file from "MyConfigurablePlugin.conf" to "ForbiddenWords.conf" also):
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# This is our global setting (can't be changed without reloading the configuration)
words:ass;asshole;bastard;bitch;cunt;fuck;motherfucker;shit;whore

# We must define our preset setting in the default preset at least
[default]

# This is our preset setting, which can be changed with "!plugin ... set ..."
# or by loading a preset.
# "100" is the default value, and any integer between 0 and 140 is allowed
immuneLevel:100|0-140
|}
Then we must prepare the plugin template itself, by renaming it from "MyConfigurablePlugin.pm" to "ForbiddenWords.pm" and editing it to replace "MyConfigurablePlugin" by "ForbiddenWords" in the source code. We must also adapt the template so that it uses the configuration settings we chose. This is done by modifying the %globalPluginParams and %presetPluginParam declarations as follows:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# We define one global setting "words" and one preset setting "immuneLevel".
# "words" has no type associated (no restriction on allowed values)
# "immuneLevel" must be an integer or an integer range
# (check %paramTypes hash in SpadsConf.pm for a complete list of allowed
# setting types)
my %globalPluginParams = ( words => [] );
my %presetPluginParams = ( immuneLevel => ['integer','integerRange'] );
|}
== Writing plugin code ==

We want our plugin to react to messages said in the battle lobby. There is no dedicated callback for this event in [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html SPADS plugin API documentation], so we have to set up our own handler on the [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#SAIDBATTLE:server SAIDBATTLE lobby command]. To do so we have to call the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addLobbyCommandHandler-handlers-priority-caller addLobbyCommandHandler]. We will call this function at the end of our plugin constructor as follows, so that it will be set up directly when the plugin is loaded:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
[...]

# We set up a lobby command handler on SAIDBATTLE
addLobbyCommandHandler({SAIDBATTLE => \&hLobbySaidBattle});

# We return the instantiated plugin
return $self;

}
|}
However, if SPADS is disconnected from the lobby due to network problems for example, all lobby handlers are automatically removed. So we must re-add them each time we connect to lobby server. This can be done using the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onLobbyConnected-self-lobbyInterface onLobbyConnected] event-based callback as follows:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# This callback is called each time we (re)connect to the lobby server
sub onLobbyConnected {

# When we are disconnected from the lobby server, all lobby command
# handlers are automatically removed, so we (re)set up our command
# handler here.
addLobbyCommandHandler({SAIDBATTLE => \&hLobbySaidBattle});

}
|}
Also, it is a good practice to remove any handler we have added when the plugin is unloaded. To do so we must implement the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback as follows:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# This callback is called when the plugin is unloaded
sub onUnload {

# We remove our lobby command handler when the plugin is unloaded
removeLobbyCommandHandler(['SAIDBATTLE']);

}
|}
Finally, we have to implement our SAIDBATTLE handler "hLobbySaidBattle". In this handler we need to perform following operations:
* skip processing if the user is the autohost itself: we need to access SPADS configuration to compare the user name with the [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:lobbyLogin lobbyLogin] setting value. So we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getSpadsConf getSpadsConf].
* perform processing according to our configuration ("words" and "immuneLevel" settings): we need to access our plugin configuration, so we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getPluginConf-pluginName-caller getPluginConf].
* retrieve the autohost access level of the user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getUserAccessLevel-user getUserAccessLevel]
* send a message to the battle lobby when we kick someone: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#sayBattle-message sayBattle].
* send a [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#KICKFROMBATTLE:client KICKFROMBATTLE] lobby command to kick a user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#queueLobbyCommand-lobbyCommand queueLobbyCommand].

Here is a commented implementation example of this "hLobbySaidBattle" handler, which will kick any non-privileged user saying a forbidden word in the battle lobby:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# This is the handler we set up on SAIDBATTLE lobby command.
# It is called each time a player says something in the battle lobby.
sub hLobbySaidBattle {

# $command is the lobby command name (SAIDBATTLE)
# $user is the name of the user who said something in the battle lobby
# $message is the message said in the battle lobby
my ($command,$user,$message)=@_;

# First we check it's not a message from SPADS (so we don't kick ourself)
my $p_spadsConf=getSpadsConf();
return if($user eq $p_spadsConf->{lobbyLogin});

# Then we check the user isn't a privileged user
# (autohost access level >= immuneLevel)
my $p_conf=getPluginConf();
return if(getUserAccessLevel($user) >= $p_conf->{immuneLevel});

# We put the forbidden words in a array
my @forbiddenWords=split(/;/,$p_conf->{words});

# We test each forbidden word
foreach my $forbiddenWord (@forbiddenWords) {

# If the message contains the forbidden word (case insensitive)
if($message =~ /\b$forbiddenWord\b/i) {

# Then we kick the user from the battle lobby
sayBattle("Kicking $user from battle (watch your language!)");
queueLobbyCommand(["KICKFROMBATTLE",$user]);

# We quit the foreach loop (no need to test other forbidden word)
last;

}

}

}
|}
Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/ForbiddenWords.pm this fully functional ForbiddenWords] plugin and [http://planetspads.free.fr/spads/plugins/tutorials/ForbiddenWords.conf its associated configuration file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the associated configuration file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: "!plugin ForbiddenWords load". And finally, as an unprivileged user we can try to say some forbidden words in the battle lobby and we should get kicked by the plugin.

 
= New-command plugin tutorial (TimePlugin) =

In this section we are going to write a plugin which implements a new command for SPADS. Such plugins are configurable plugins like the one we wrote just before, with 2 additional files to configure the new commands. This plugin will give current time when someone types "!time".

== Preparing the template ==

This time we need to download 4 files to prepare our plugin: [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPlugin.pm the new-command plugin template], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPlugin.conf the associated configuration file example], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginHelp.dat the help file example] and [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginCmd.conf the commands rights configuration file example].

As usual, we rename these files to match our plugin name: "MyNewCommandPlugin" --> "TimePlugin". Then we edit the plugin template TimePlugin.pm and replace "MyNewCommandPlugin" by "TimePlugin" in the source code, and we do the same for the plugin configuration template TimePlugin.conf, so that the "commandsFile" and "helpFile" settings are consistent with the files we just renamed.

Then we can edit our command rights requirements configuration file: TimePluginCmd.conf. This file uses the same syntax as the standard SPADS commands.conf file. The template provides a default command "myCommand" with no requirement. We will just rename this command to "time":
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# Anyone can call our command from anywhere
[time]
::|0:
|}
Now we need to write the help information for our new command. This is done in the file TimePluginHelp.dat. This file uses the same syntax as the standard SPADS help.dat file, and the template provides a help example for a command "myCommand" as a syntax reminder. After each command declaration, the first line is the command syntax description, and the other lines are optional usage examples. Let's replace this help example with our own help information for our basic !time command:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
[time]
<nowiki>!</nowiki>time - This command just prints current time
|}
== Writing plugin code ==

The new-command plugin template that we used to initialize our plugin already defines a new command named "myCommand", so all we have to do is to edit our plugin file ( TimePlugin.pm ) and replace this command by our own "time" command:

First, let's modify the code which sets up the new SPADS command handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addSpadsCommandHandler-handlers-replace-0 addSpadsCommandHandler]. This call is located in the plugin constructor. We edit it so that it becomes:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
[...]
# We declare our new command and the associated handler
addSpadsCommandHandler({time => \&hSpadsTime});
[...]
|}
We must modify the same way the code which removes this SPADS handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#removeSpadsCommandHandler-commands removeSpadsCommandHandler] in the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
[...]
# We remove our new command handler
removeSpadsCommandHandler(['time']);
[...]
|}
Finally, we must replace the handler example "hMyCommand" by our own handler "hSpadsTime". In order to answer to the user issuing the command, we can use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#answer-message answer], which will send an answer message to the user in the same way he sent the command (private message, battle lobby...).

Here is an implementation example for this basic command:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# This is the handler for our new command
sub hSpadsTime {
my ($source,$user,$p_params,$checkOnly)=@_;

# time is a basic command, we have nothing to check in case of callvote
return 1 if($checkOnly);

my @time = localtime();
@time = map(sprintf("%02d",$_),@time);

answer("Current local time: $time[2]:$time[1]:$time[0]");
}
|}

Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/TimePlugin.pm this fully functional TimePlugin] plugin, and its associated [http://planetspads.free.fr/spads/plugins/tutorials/TimePlugin.conf configuration file], [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginCmd.conf command rights configuration file] and [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginHelp.dat command help file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module and the plugin help file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the 2 configuration files in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: "!plugin TimePlugin load". And finally, we can try to say !time in a private message to SPADS or in the battle lobby, and SPADS should answer giving current local time. Our !time command help should also appear in "!help" and "!help time" outputs.

[[Category:SPADS]]

SPADS plugin development

2021-01-28T07:32:38Z

Bibim:

= Introduction =

SPADS is an autohost system coded in Perl, it supports both Perl and Python plugins. This tutorial deals with Perl plugin development only (for Python plugin development another tutorial is available [https://springrts.com/wiki/SPADS_plugin_development_(Python) here]).

SPADS plugins are object-oriented modules. It is strongly recommended to already know Perl basics before starting Perl plugin development (a brief introduction to Perl is available [https://perldoc.perl.org/perlintro here]).

 
= 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 [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] (the <code>.py</code> files must be ignored for this tutorial, these are the Python versions of the templates).

Our first plugin will be very basic, so we will use the simplest template: <code>MySimplePlugin.pm</code>. 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 <code>HelloWorld</code>. We have to rename the downloaded template from <code>MySimplePlugin.pm</code> to <code>HelloWorld.pm</code>, and edit it to replace <code>MySimplePlugin</code> by <code>HelloWorld</code> 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 <code>spads.conf</code> configuration file and reload SPADS configuration).

We have to move our new plugin (<code>HelloWorld.pm</code>) 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): <code>!plugin HelloWorld load</code>. SPADS should answer <code>Loaded plugin HelloWorld.</code>, 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-self-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 <code>onPrivateMsg</code> callback, which will answer <code>Hello World</code> to anyone saying <code>Hello</code> in a private message to SPADS:
<syntaxhighlight lang="perl">
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;

}</syntaxhighlight>

All we have to do now is adding this callback declaration in our <code>HelloWorld.pm</code> 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: <code>!plugin HelloWorld reload</code>. SPADS should answer <code>Reloaded plugin HelloWorld.</code>, which indicates the plugin has been reloaded successfully.

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

 
= Configurable plugin tutorial (ForbiddenWords) =

In this section we are going to write our first configurable SPADS plugin (a configurable plugin has its own configuration file, named after the plugin name but with ".conf" extension). This plugin will monitor all messages said by players in the battle lobby, and will kick players who use swear words.

== Specifying our configuration parameters ==

The first step of writing a configurable plugin is to choose how we will configure it. In our example, we will use 2 configuration parameters: "words" will contain the list of forbidden words, and "immuneLevel" will contain the minimum autohost access level to be immune regarding these forbidden words checks.

We choose to make "words" a global setting (unmodifiable, not impacted by preset change), and "immuneLevel" a preset setting (modifiable, can be impacted by preset change). The "words" global setting will have no restriction (can be empty, can contain any character...), whereas the "immuneLevel" preset setting will only be allowed to be an integer or integer range.

== Preparing the template ==

Once we have a clear view of our configuration settings, we can start adapting the template for our needs. Since we are making a configurable plugin, this time we will download [http://planetspads.free.fr/spads/plugins/templates/commented/MyConfigurablePlugin.pm the configurable plugin template] and its associated [http://planetspads.free.fr/spads/plugins/templates/commented/MyConfigurablePlugin.conf configuration file example].

First, let's take a look at the configuration file example. This is a just a basic configuration file containing one global setting example and one preset setting example. Let's modify this file to match the configuration we chose as follows (don't forget to rename the file from "MyConfigurablePlugin.conf" to "ForbiddenWords.conf" also):
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# This is our global setting (can't be changed without reloading the configuration)
words:ass;asshole;bastard;bitch;cunt;fuck;motherfucker;shit;whore

# We must define our preset setting in the default preset at least
[default]

# This is our preset setting, which can be changed with "!plugin ... set ..."
# or by loading a preset.
# "100" is the default value, and any integer between 0 and 140 is allowed
immuneLevel:100|0-140
|}
Then we must prepare the plugin template itself, by renaming it from "MyConfigurablePlugin.pm" to "ForbiddenWords.pm" and editing it to replace "MyConfigurablePlugin" by "ForbiddenWords" in the source code. We must also adapt the template so that it uses the configuration settings we chose. This is done by modifying the %globalPluginParams and %presetPluginParam declarations as follows:
<syntaxhighlight lang="perl">
# We define one global setting "words" and one preset setting "immuneLevel".
# "words" has no type associated (no restriction on allowed values)
# "immuneLevel" must be an integer or an integer range
# (check %paramTypes hash in SpadsConf.pm for a complete list of allowed
# setting types)
my %globalPluginParams = ( words => [] );
my %presetPluginParams = ( immuneLevel => ['integer','integerRange'] );
</syntaxhighlight>

== Writing plugin code ==

We want our plugin to react to messages said in the battle lobby. There is no dedicated callback for this event in [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html SPADS plugin API documentation], so we have to set up our own handler on the [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#SAIDBATTLE:server SAIDBATTLE lobby command]. To do so we have to call the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addLobbyCommandHandler-handlers-priority-caller addLobbyCommandHandler]. We will call this function at the end of our plugin constructor as follows, so that it will be set up directly when the plugin is loaded:
<syntaxhighlight lang="perl">
[...]

# We set up a lobby command handler on SAIDBATTLE
addLobbyCommandHandler({SAIDBATTLE => \&hLobbySaidBattle});

# We return the instantiated plugin
return $self;

}
</syntaxhighlight>
However, if SPADS is disconnected from the lobby due to network problems for example, all lobby handlers are automatically removed. So we must re-add them each time we connect to lobby server. This can be done using the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onLobbyConnected-self-lobbyInterface onLobbyConnected] event-based callback as follows:
<syntaxhighlight lang="perl">
# This callback is called each time we (re)connect to the lobby server
sub onLobbyConnected {

# When we are disconnected from the lobby server, all lobby command
# handlers are automatically removed, so we (re)set up our command
# handler here.
addLobbyCommandHandler({SAIDBATTLE => \&hLobbySaidBattle});

}
</syntaxhighlight>
Also, it is a good practice to remove any handler we have added when the plugin is unloaded. To do so we must implement the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback as follows:
<syntaxhighlight lang="perl">
# This callback is called when the plugin is unloaded
sub onUnload {

# We remove our lobby command handler when the plugin is unloaded
removeLobbyCommandHandler(['SAIDBATTLE']);

}
</syntaxhighlight>
Finally, we have to implement our SAIDBATTLE handler "hLobbySaidBattle". In this handler we need to perform following operations:
* skip processing if the user is the autohost itself: we need to access SPADS configuration to compare the user name with the [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:lobbyLogin lobbyLogin] setting value. So we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getSpadsConf getSpadsConf].
* perform processing according to our configuration ("words" and "immuneLevel" settings): we need to access our plugin configuration, so we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getPluginConf-pluginName-caller getPluginConf].
* retrieve the autohost access level of the user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getUserAccessLevel-user getUserAccessLevel]
* send a message to the battle lobby when we kick someone: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#sayBattle-message sayBattle].
* send a [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#KICKFROMBATTLE:client KICKFROMBATTLE] lobby command to kick a user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#queueLobbyCommand-lobbyCommand queueLobbyCommand].

Here is a commented implementation example of this "hLobbySaidBattle" handler, which will kick any non-privileged user saying a forbidden word in the battle lobby:
<syntaxhighlight lang="perl">
# This is the handler we set up on SAIDBATTLE lobby command.
# It is called each time a player says something in the battle lobby.
sub hLobbySaidBattle {

# $command is the lobby command name (SAIDBATTLE)
# $user is the name of the user who said something in the battle lobby
# $message is the message said in the battle lobby
my ($command,$user,$message)=@_;

# First we check it's not a message from SPADS (so we don't kick ourself)
my $p_spadsConf=getSpadsConf();
return if($user eq $p_spadsConf->{lobbyLogin});

# Then we check the user isn't a privileged user
# (autohost access level >= immuneLevel)
my $p_conf=getPluginConf();
return if(getUserAccessLevel($user) >= $p_conf->{immuneLevel});

# We put the forbidden words in a array
my @forbiddenWords=split(/;/,$p_conf->{words});

# We test each forbidden word
foreach my $forbiddenWord (@forbiddenWords) {

# If the message contains the forbidden word (case insensitive)
if($message =~ /\b$forbiddenWord\b/i) {

# Then we kick the user from the battle lobby
sayBattle("Kicking $user from battle (watch your language!)");
queueLobbyCommand(["KICKFROMBATTLE",$user]);

# We quit the foreach loop (no need to test other forbidden word)
last;

}

}

}
</syntaxhighlight>
Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/ForbiddenWords.pm this fully functional ForbiddenWords] plugin and [http://planetspads.free.fr/spads/plugins/tutorials/ForbiddenWords.conf its associated configuration file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the associated configuration file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: "!plugin ForbiddenWords load". And finally, as an unprivileged user we can try to say some forbidden words in the battle lobby and we should get kicked by the plugin.

 
= New-command plugin tutorial (TimePlugin) =

In this section we are going to write a plugin which implements a new command for SPADS. Such plugins are configurable plugins like the one we wrote just before, with 2 additional files to configure the new commands. This plugin will give current time when someone types "!time".

== Preparing the template ==

This time we need to download 4 files to prepare our plugin: [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPlugin.pm the new-command plugin template], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPlugin.conf the associated configuration file example], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginHelp.dat the help file example] and [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginCmd.conf the commands rights configuration file example].

As usual, we rename these files to match our plugin name: "MyNewCommandPlugin" --> "TimePlugin". Then we edit the plugin template TimePlugin.pm and replace "MyNewCommandPlugin" by "TimePlugin" in the source code, and we do the same for the plugin configuration template TimePlugin.conf, so that the "commandsFile" and "helpFile" settings are consistent with the files we just renamed.

Then we can edit our command rights requirements configuration file: TimePluginCmd.conf. This file uses the same syntax as the standard SPADS commands.conf file. The template provides a default command "myCommand" with no requirement. We will just rename this command to "time":
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# Anyone can call our command from anywhere
[time]
::|0:
|}
Now we need to write the help information for our new command. This is done in the file TimePluginHelp.dat. This file uses the same syntax as the standard SPADS help.dat file, and the template provides a help example for a command "myCommand" as a syntax reminder. After each command declaration, the first line is the command syntax description, and the other lines are optional usage examples. Let's replace this help example with our own help information for our basic !time command:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
[time]
<nowiki>!</nowiki>time - This command just prints current time
|}
== Writing plugin code ==

The new-command plugin template that we used to initialize our plugin already defines a new command named "myCommand", so all we have to do is to edit our plugin file ( TimePlugin.pm ) and replace this command by our own "time" command:

First, let's modify the code which sets up the new SPADS command handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addSpadsCommandHandler-handlers-replace-0 addSpadsCommandHandler]. This call is located in the plugin constructor. We edit it so that it becomes:
<syntaxhighlight lang="perl">
[...]
# We declare our new command and the associated handler
addSpadsCommandHandler({time => \&hSpadsTime});
[...]
</syntaxhighlight>
We must modify the same way the code which removes this SPADS handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#removeSpadsCommandHandler-commands removeSpadsCommandHandler] in the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback:
<syntaxhighlight lang="perl">
[...]
# We remove our new command handler
removeSpadsCommandHandler(['time']);
[...]
</syntaxhighlight>
Finally, we must replace the handler example "hMyCommand" by our own handler "hSpadsTime". In order to answer to the user issuing the command, we can use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#answer-message answer], which will send an answer message to the user in the same way he sent the command (private message, battle lobby...).

Here is an implementation example for this basic command:
<syntaxhighlight lang="perl">
# This is the handler for our new command
sub hSpadsTime {
my ($source,$user,$p_params,$checkOnly)=@_;

# time is a basic command, we have nothing to check in case of callvote
return 1 if($checkOnly);

my @time = localtime();
@time = map(sprintf("%02d",$_),@time);

answer("Current local time: $time[2]:$time[1]:$time[0]");
}
</syntaxhighlight>

Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/TimePlugin.pm this fully functional TimePlugin] plugin, and its associated [http://planetspads.free.fr/spads/plugins/tutorials/TimePlugin.conf configuration file], [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginCmd.conf command rights configuration file] and [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginHelp.dat command help file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module and the plugin help file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the 2 configuration files in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: "!plugin TimePlugin load". And finally, we can try to say !time in a private message to SPADS or in the battle lobby, and SPADS should answer giving current local time. Our !time command help should also appear in "!help" and "!help time" outputs.

[[Category:SPADS]]

SPADS plugin development (Python)

2021-01-28T07:31:33Z

Bibim:

= Introduction =

SPADS is an autohost system coded in Perl, it supports both Perl and Python plugins. This tutorial deals with Python plugin development only (for Perl plugin development another tutorial is available [https://springrts.com/wiki/SPADS_plugin_development here]).

SPADS plugins are object-oriented modules. It is strongly recommended to already know Python basics before starting Python plugin development (a Python tutorial is available [https://docs.python.org/3/tutorial/ here]).

 
= Technical prerequisites =

Python (the Python interpreter and its libraries) must be installed on the system (versions 2.6+ or 3.2+ recommended). The type of installation (32-bit / 64-bit) must be consistent with the Perl version and the Spring engine used for SPADS.

Additionally, in order to allow communication between Perl code (SPADS core) and Python code (SPADS plugins), SPADS uses a Perl module named <code>Inline::Python</code> which must also be installed on the system. It is recommended to install latest version for SPADS, refer to [https://springrts.com/wiki/SPADS_Inline::Python_installation_guide this guide] for installation.

 
= 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 [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] (the <code>.pm</code> files must be ignored for this tutorial, these are the Perl versions of the templates).

Our first plugin will be very basic, so we will use the simplest template: <code>mysimpleplugin.py</code>. Let's download [http://planetspads.free.fr/spads/plugins/templates/commented/mysimpleplugin.py 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 <code>HelloWorld</code>. We have to rename the downloaded template from <code>mysimpleplugin.py</code> to <code>helloworld.py</code>, and edit it to replace <code>MySimplePlugin</code> by <code>HelloWorld</code> 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 <code>spads.conf</code> configuration file and reload SPADS configuration).

We have to move our new plugin (<code>helloworld.py</code>) 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): <code>!plugin HelloWorld load</code>. SPADS should answer <code>Loaded plugin HelloWorld.</code>, 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-self-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 <code>onPrivateMsg</code> callback, which will answer <code>Hello World</code> to anyone saying <code>Hello</code> in a private message to SPADS:
<syntaxhighlight lang="python">
# This is the callback called each time SPADS receives a private message
# 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
def onPrivateMsg(self,userName,message):

# Here we "fix" strings received from Perl in case
# the Inline::Python module transmits them as byte strings
(userName,message)=spads.fix_string(userName,message)

# We check the message sent by the user is "Hello"
if message == 'Hello':

# We send our wonderful Hello World message
spads.sayPrivate(userName,'Hello World')

# We return 0 because we don't want to filter out private messages
# for other SPADS processing
return 0</syntaxhighlight>

All we have to do now is adding this callback declaration in our <code>helloworld.py</code> file located in SPADS plugins directory. We obtain [http://planetspads.free.fr/spads/plugins/tutorials/helloworld.py 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: <code>!plugin HelloWorld reload</code>. SPADS should answer <code>Reloaded plugin HelloWorld.</code>, which indicates the plugin has been reloaded successfully.

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

'''/!\ WORK IN PROGRESS /!\'''

 
= Configurable plugin tutorial (ForbiddenWords) =

In this section we are going to write our first configurable SPADS plugin (a configurable plugin has its own configuration file, named after the plugin name but with ".conf" extension). This plugin will monitor all messages said by players in the battle lobby, and will kick players who use swear words.

== Specifying our configuration parameters ==

The first step of writing a configurable plugin is to choose how we will configure it. In our example, we will use 2 configuration parameters: "words" will contain the list of forbidden words, and "immuneLevel" will contain the minimum autohost access level to be immune regarding these forbidden words checks.

We choose to make "words" a global setting (unmodifiable, not impacted by preset change), and "immuneLevel" a preset setting (modifiable, can be impacted by preset change). The "words" global setting will have no restriction (can be empty, can contain any character...), whereas the "immuneLevel" preset setting will only be allowed to be an integer or integer range.

== Preparing the template ==

Once we have a clear view of our configuration settings, we can start adapting the template for our needs. Since we are making a configurable plugin, this time we will download [http://planetspads.free.fr/spads/plugins/templates/commented/MyConfigurablePlugin.pm the configurable plugin template] and its associated [http://planetspads.free.fr/spads/plugins/templates/commented/MyConfigurablePlugin.conf configuration file example].

First, let's take a look at the configuration file example. This is a just a basic configuration file containing one global setting example and one preset setting example. Let's modify this file to match the configuration we chose as follows (don't forget to rename the file from "MyConfigurablePlugin.conf" to "ForbiddenWords.conf" also):
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# This is our global setting (can't be changed without reloading the configuration)
words:ass;asshole;bastard;bitch;cunt;fuck;motherfucker;shit;whore

# We must define our preset setting in the default preset at least
[default]

# This is our preset setting, which can be changed with "!plugin ... set ..."
# or by loading a preset.
# "100" is the default value, and any integer between 0 and 140 is allowed
immuneLevel:100|0-140
|}
Then we must prepare the plugin template itself, by renaming it from "MyConfigurablePlugin.pm" to "ForbiddenWords.pm" and editing it to replace "MyConfigurablePlugin" by "ForbiddenWords" in the source code. We must also adapt the template so that it uses the configuration settings we chose. This is done by modifying the %globalPluginParams and %presetPluginParam declarations as follows:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# We define one global setting "words" and one preset setting "immuneLevel".
# "words" has no type associated (no restriction on allowed values)
# "immuneLevel" must be an integer or an integer range
# (check %paramTypes hash in SpadsConf.pm for a complete list of allowed
# setting types)
my %globalPluginParams = ( words => [] );
my %presetPluginParams = ( immuneLevel => ['integer','integerRange'] );
|}
== Writing plugin code ==

We want our plugin to react to messages said in the battle lobby. There is no dedicated callback for this event in [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html SPADS plugin API documentation], so we have to set up our own handler on the [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#SAIDBATTLE:server SAIDBATTLE lobby command]. To do so we have to call the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addLobbyCommandHandler-handlers-priority-caller addLobbyCommandHandler]. We will call this function at the end of our plugin constructor as follows, so that it will be set up directly when the plugin is loaded:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
[...]

# We set up a lobby command handler on SAIDBATTLE
addLobbyCommandHandler({SAIDBATTLE => \&hLobbySaidBattle});

# We return the instantiated plugin
return $self;

}
|}
However, if SPADS is disconnected from the lobby due to network problems for example, all lobby handlers are automatically removed. So we must re-add them each time we connect to lobby server. This can be done using the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onLobbyConnected-self-lobbyInterface onLobbyConnected] event-based callback as follows:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# This callback is called each time we (re)connect to the lobby server
sub onLobbyConnected {

# When we are disconnected from the lobby server, all lobby command
# handlers are automatically removed, so we (re)set up our command
# handler here.
addLobbyCommandHandler({SAIDBATTLE => \&hLobbySaidBattle});

}
|}
Also, it is a good practice to remove any handler we have added when the plugin is unloaded. To do so we must implement the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback as follows:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# This callback is called when the plugin is unloaded
sub onUnload {

# We remove our lobby command handler when the plugin is unloaded
removeLobbyCommandHandler(['SAIDBATTLE']);

}
|}
Finally, we have to implement our SAIDBATTLE handler "hLobbySaidBattle". In this handler we need to perform following operations:
* skip processing if the user is the autohost itself: we need to access SPADS configuration to compare the user name with the [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:lobbyLogin lobbyLogin] setting value. So we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getSpadsConf getSpadsConf].
* perform processing according to our configuration ("words" and "immuneLevel" settings): we need to access our plugin configuration, so we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getPluginConf-pluginName-caller getPluginConf].
* retrieve the autohost access level of the user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getUserAccessLevel-user getUserAccessLevel]
* send a message to the battle lobby when we kick someone: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#sayBattle-message sayBattle].
* send a [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#KICKFROMBATTLE:client KICKFROMBATTLE] lobby command to kick a user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#queueLobbyCommand-lobbyCommand queueLobbyCommand].

Here is a commented implementation example of this "hLobbySaidBattle" handler, which will kick any non-privileged user saying a forbidden word in the battle lobby:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# This is the handler we set up on SAIDBATTLE lobby command.
# It is called each time a player says something in the battle lobby.
sub hLobbySaidBattle {

# $command is the lobby command name (SAIDBATTLE)
# $user is the name of the user who said something in the battle lobby
# $message is the message said in the battle lobby
my ($command,$user,$message)=@_;

# First we check it's not a message from SPADS (so we don't kick ourself)
my $p_spadsConf=getSpadsConf();
return if($user eq $p_spadsConf->{lobbyLogin});

# Then we check the user isn't a privileged user
# (autohost access level >= immuneLevel)
my $p_conf=getPluginConf();
return if(getUserAccessLevel($user) >= $p_conf->{immuneLevel});

# We put the forbidden words in a array
my @forbiddenWords=split(/;/,$p_conf->{words});

# We test each forbidden word
foreach my $forbiddenWord (@forbiddenWords) {

# If the message contains the forbidden word (case insensitive)
if($message =~ /\b$forbiddenWord\b/i) {

# Then we kick the user from the battle lobby
sayBattle("Kicking $user from battle (watch your language!)");
queueLobbyCommand(["KICKFROMBATTLE",$user]);

# We quit the foreach loop (no need to test other forbidden word)
last;

}

}

}
|}
Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/ForbiddenWords.pm this fully functional ForbiddenWords] plugin and [http://planetspads.free.fr/spads/plugins/tutorials/ForbiddenWords.conf its associated configuration file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the associated configuration file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: "!plugin ForbiddenWords load". And finally, as an unprivileged user we can try to say some forbidden words in the battle lobby and we should get kicked by the plugin.

 
= New-command plugin tutorial (TimePlugin) =

In this section we are going to write a plugin which implements a new command for SPADS. Such plugins are configurable plugins like the one we wrote just before, with 2 additional files to configure the new commands. This plugin will give current time when someone types "!time".

== Preparing the template ==

This time we need to download 4 files to prepare our plugin: [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPlugin.pm the new-command plugin template], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPlugin.conf the associated configuration file example], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginHelp.dat the help file example] and [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginCmd.conf the commands rights configuration file example].

As usual, we rename these files to match our plugin name: "MyNewCommandPlugin" --> "TimePlugin". Then we edit the plugin template TimePlugin.pm and replace "MyNewCommandPlugin" by "TimePlugin" in the source code, and we do the same for the plugin configuration template TimePlugin.conf, so that the "commandsFile" and "helpFile" settings are consistent with the files we just renamed.

Then we can edit our command rights requirements configuration file: TimePluginCmd.conf. This file uses the same syntax as the standard SPADS commands.conf file. The template provides a default command "myCommand" with no requirement. We will just rename this command to "time":
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# Anyone can call our command from anywhere
[time]
::|0:
|}
Now we need to write the help information for our new command. This is done in the file TimePluginHelp.dat. This file uses the same syntax as the standard SPADS help.dat file, and the template provides a help example for a command "myCommand" as a syntax reminder. After each command declaration, the first line is the command syntax description, and the other lines are optional usage examples. Let's replace this help example with our own help information for our basic !time command:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
[time]
<nowiki>!</nowiki>time - This command just prints current time
|}
== Writing plugin code ==

The new-command plugin template that we used to initialize our plugin already defines a new command named "myCommand", so all we have to do is to edit our plugin file ( TimePlugin.pm ) and replace this command by our own "time" command:

First, let's modify the code which sets up the new SPADS command handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addSpadsCommandHandler-handlers-replace-0 addSpadsCommandHandler]. This call is located in the plugin constructor. We edit it so that it becomes:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
[...]
# We declare our new command and the associated handler
addSpadsCommandHandler({time => \&hSpadsTime});
[...]
|}
We must modify the same way the code which removes this SPADS handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#removeSpadsCommandHandler-commands removeSpadsCommandHandler] in the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
[...]
# We remove our new command handler
removeSpadsCommandHandler(['time']);
[...]
|}
Finally, we must replace the handler example "hMyCommand" by our own handler "hSpadsTime". In order to answer to the user issuing the command, we can use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#answer-message answer], which will send an answer message to the user in the same way he sent the command (private message, battle lobby...).

Here is an implementation example for this basic command:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# This is the handler for our new command
sub hSpadsTime {
my ($source,$user,$p_params,$checkOnly)=@_;

# time is a basic command, we have nothing to check in case of callvote
return 1 if($checkOnly);

my @time = localtime();
@time = map(sprintf("%02d",$_),@time);

answer("Current local time: $time[2]:$time[1]:$time[0]");
}
|}

Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/TimePlugin.pm this fully functional TimePlugin] plugin, and its associated [http://planetspads.free.fr/spads/plugins/tutorials/TimePlugin.conf configuration file], [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginCmd.conf command rights configuration file] and [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginHelp.dat command help file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module and the plugin help file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the 2 configuration files in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: "!plugin TimePlugin load". And finally, we can try to say !time in a private message to SPADS or in the battle lobby, and SPADS should answer giving current local time. Our !time command help should also appear in "!help" and "!help time" outputs.

[[Category:SPADS]]

SPADS plugin development (Python)

2021-01-28T07:29:57Z

Bibim:

= Introduction =

SPADS is an autohost system coded in Perl, it supports both Perl and Python plugins. This tutorial deals with Python plugin development only (for Perl plugin development another tutorial is available [https://springrts.com/wiki/SPADS_plugin_development here]).

SPADS plugins are object-oriented modules. It is strongly recommended to already know Python basics before starting Python plugin development (a Python tutorial is available [https://docs.python.org/3/tutorial/ here]).

= Technical prerequisites =

Python (the Python interpreter and its libraries) must be installed on the system (versions 2.6+ or 3.2+ recommended). The type of installation (32-bit / 64-bit) must be consistent with the Perl version and the Spring engine used for SPADS.

Additionally, in order to allow communication between Perl code (SPADS core) and Python code (SPADS plugins), SPADS uses a Perl module named <code>Inline::Python</code> which must also be installed on the system. It is recommended to install latest version for SPADS, refer to [https://springrts.com/wiki/SPADS_Inline::Python_installation_guide this guide] for installation.

= 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 [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] (the <code>.pm</code> files must be ignored for this tutorial, these are the Perl versions of the templates).

Our first plugin will be very basic, so we will use the simplest template: <code>mysimpleplugin.py</code>. Let's download [http://planetspads.free.fr/spads/plugins/templates/commented/mysimpleplugin.py 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 <code>HelloWorld</code>. We have to rename the downloaded template from <code>mysimpleplugin.py</code> to <code>helloworld.py</code>, and edit it to replace <code>MySimplePlugin</code> by <code>HelloWorld</code> 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 <code>spads.conf</code> configuration file and reload SPADS configuration).

We have to move our new plugin (<code>helloworld.py</code>) 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): <code>!plugin HelloWorld load</code>. SPADS should answer <code>Loaded plugin HelloWorld.</code>, 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-self-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 <code>onPrivateMsg</code> callback, which will answer <code>Hello World</code> to anyone saying <code>Hello</code> in a private message to SPADS:
<syntaxhighlight lang="python">
# This is the callback called each time SPADS receives a private message
# 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
def onPrivateMsg(self,userName,message):

# Here we "fix" strings received from Perl in case
# the Inline::Python module transmits them as byte strings
(userName,message)=spads.fix_string(userName,message)

# We check the message sent by the user is "Hello"
if message == 'Hello':

# We send our wonderful Hello World message
spads.sayPrivate(userName,'Hello World')

# We return 0 because we don't want to filter out private messages
# for other SPADS processing
return 0</syntaxhighlight>

All we have to do now is adding this callback declaration in our <code>helloworld.py</code> file located in SPADS plugins directory. We obtain [http://planetspads.free.fr/spads/plugins/tutorials/helloworld.py 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: <code>!plugin HelloWorld reload</code>. SPADS should answer <code>Reloaded plugin HelloWorld.</code>, which indicates the plugin has been reloaded successfully.

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

'''/!\ WORK IN PROGRESS /!\'''

= Configurable plugin tutorial (ForbiddenWords) =

In this section we are going to write our first configurable SPADS plugin (a configurable plugin has its own configuration file, named after the plugin name but with ".conf" extension). This plugin will monitor all messages said by players in the battle lobby, and will kick players who use swear words.

== Specifying our configuration parameters ==

The first step of writing a configurable plugin is to choose how we will configure it. In our example, we will use 2 configuration parameters: "words" will contain the list of forbidden words, and "immuneLevel" will contain the minimum autohost access level to be immune regarding these forbidden words checks.

We choose to make "words" a global setting (unmodifiable, not impacted by preset change), and "immuneLevel" a preset setting (modifiable, can be impacted by preset change). The "words" global setting will have no restriction (can be empty, can contain any character...), whereas the "immuneLevel" preset setting will only be allowed to be an integer or integer range.

== Preparing the template ==

Once we have a clear view of our configuration settings, we can start adapting the template for our needs. Since we are making a configurable plugin, this time we will download [http://planetspads.free.fr/spads/plugins/templates/commented/MyConfigurablePlugin.pm the configurable plugin template] and its associated [http://planetspads.free.fr/spads/plugins/templates/commented/MyConfigurablePlugin.conf configuration file example].

First, let's take a look at the configuration file example. This is a just a basic configuration file containing one global setting example and one preset setting example. Let's modify this file to match the configuration we chose as follows (don't forget to rename the file from "MyConfigurablePlugin.conf" to "ForbiddenWords.conf" also):
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# This is our global setting (can't be changed without reloading the configuration)
words:ass;asshole;bastard;bitch;cunt;fuck;motherfucker;shit;whore

# We must define our preset setting in the default preset at least
[default]

# This is our preset setting, which can be changed with "!plugin ... set ..."
# or by loading a preset.
# "100" is the default value, and any integer between 0 and 140 is allowed
immuneLevel:100|0-140
|}
Then we must prepare the plugin template itself, by renaming it from "MyConfigurablePlugin.pm" to "ForbiddenWords.pm" and editing it to replace "MyConfigurablePlugin" by "ForbiddenWords" in the source code. We must also adapt the template so that it uses the configuration settings we chose. This is done by modifying the %globalPluginParams and %presetPluginParam declarations as follows:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# We define one global setting "words" and one preset setting "immuneLevel".
# "words" has no type associated (no restriction on allowed values)
# "immuneLevel" must be an integer or an integer range
# (check %paramTypes hash in SpadsConf.pm for a complete list of allowed
# setting types)
my %globalPluginParams = ( words => [] );
my %presetPluginParams = ( immuneLevel => ['integer','integerRange'] );
|}
== Writing plugin code ==

We want our plugin to react to messages said in the battle lobby. There is no dedicated callback for this event in [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html SPADS plugin API documentation], so we have to set up our own handler on the [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#SAIDBATTLE:server SAIDBATTLE lobby command]. To do so we have to call the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addLobbyCommandHandler-handlers-priority-caller addLobbyCommandHandler]. We will call this function at the end of our plugin constructor as follows, so that it will be set up directly when the plugin is loaded:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
[...]

# We set up a lobby command handler on SAIDBATTLE
addLobbyCommandHandler({SAIDBATTLE => \&hLobbySaidBattle});

# We return the instantiated plugin
return $self;

}
|}
However, if SPADS is disconnected from the lobby due to network problems for example, all lobby handlers are automatically removed. So we must re-add them each time we connect to lobby server. This can be done using the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onLobbyConnected-self-lobbyInterface onLobbyConnected] event-based callback as follows:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# This callback is called each time we (re)connect to the lobby server
sub onLobbyConnected {

# When we are disconnected from the lobby server, all lobby command
# handlers are automatically removed, so we (re)set up our command
# handler here.
addLobbyCommandHandler({SAIDBATTLE => \&hLobbySaidBattle});

}
|}
Also, it is a good practice to remove any handler we have added when the plugin is unloaded. To do so we must implement the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback as follows:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# This callback is called when the plugin is unloaded
sub onUnload {

# We remove our lobby command handler when the plugin is unloaded
removeLobbyCommandHandler(['SAIDBATTLE']);

}
|}
Finally, we have to implement our SAIDBATTLE handler "hLobbySaidBattle". In this handler we need to perform following operations:
* skip processing if the user is the autohost itself: we need to access SPADS configuration to compare the user name with the [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:lobbyLogin lobbyLogin] setting value. So we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getSpadsConf getSpadsConf].
* perform processing according to our configuration ("words" and "immuneLevel" settings): we need to access our plugin configuration, so we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getPluginConf-pluginName-caller getPluginConf].
* retrieve the autohost access level of the user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getUserAccessLevel-user getUserAccessLevel]
* send a message to the battle lobby when we kick someone: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#sayBattle-message sayBattle].
* send a [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#KICKFROMBATTLE:client KICKFROMBATTLE] lobby command to kick a user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#queueLobbyCommand-lobbyCommand queueLobbyCommand].

Here is a commented implementation example of this "hLobbySaidBattle" handler, which will kick any non-privileged user saying a forbidden word in the battle lobby:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# This is the handler we set up on SAIDBATTLE lobby command.
# It is called each time a player says something in the battle lobby.
sub hLobbySaidBattle {

# $command is the lobby command name (SAIDBATTLE)
# $user is the name of the user who said something in the battle lobby
# $message is the message said in the battle lobby
my ($command,$user,$message)=@_;

# First we check it's not a message from SPADS (so we don't kick ourself)
my $p_spadsConf=getSpadsConf();
return if($user eq $p_spadsConf->{lobbyLogin});

# Then we check the user isn't a privileged user
# (autohost access level >= immuneLevel)
my $p_conf=getPluginConf();
return if(getUserAccessLevel($user) >= $p_conf->{immuneLevel});

# We put the forbidden words in a array
my @forbiddenWords=split(/;/,$p_conf->{words});

# We test each forbidden word
foreach my $forbiddenWord (@forbiddenWords) {

# If the message contains the forbidden word (case insensitive)
if($message =~ /\b$forbiddenWord\b/i) {

# Then we kick the user from the battle lobby
sayBattle("Kicking $user from battle (watch your language!)");
queueLobbyCommand(["KICKFROMBATTLE",$user]);

# We quit the foreach loop (no need to test other forbidden word)
last;

}

}

}
|}
Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/ForbiddenWords.pm this fully functional ForbiddenWords] plugin and [http://planetspads.free.fr/spads/plugins/tutorials/ForbiddenWords.conf its associated configuration file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the associated configuration file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: "!plugin ForbiddenWords load". And finally, as an unprivileged user we can try to say some forbidden words in the battle lobby and we should get kicked by the plugin.

= New-command plugin tutorial (TimePlugin) =

In this section we are going to write a plugin which implements a new command for SPADS. Such plugins are configurable plugins like the one we wrote just before, with 2 additional files to configure the new commands. This plugin will give current time when someone types "!time".

== Preparing the template ==

This time we need to download 4 files to prepare our plugin: [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPlugin.pm the new-command plugin template], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPlugin.conf the associated configuration file example], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginHelp.dat the help file example] and [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginCmd.conf the commands rights configuration file example].

As usual, we rename these files to match our plugin name: "MyNewCommandPlugin" --> "TimePlugin". Then we edit the plugin template TimePlugin.pm and replace "MyNewCommandPlugin" by "TimePlugin" in the source code, and we do the same for the plugin configuration template TimePlugin.conf, so that the "commandsFile" and "helpFile" settings are consistent with the files we just renamed.

Then we can edit our command rights requirements configuration file: TimePluginCmd.conf. This file uses the same syntax as the standard SPADS commands.conf file. The template provides a default command "myCommand" with no requirement. We will just rename this command to "time":
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# Anyone can call our command from anywhere
[time]
::|0:
|}
Now we need to write the help information for our new command. This is done in the file TimePluginHelp.dat. This file uses the same syntax as the standard SPADS help.dat file, and the template provides a help example for a command "myCommand" as a syntax reminder. After each command declaration, the first line is the command syntax description, and the other lines are optional usage examples. Let's replace this help example with our own help information for our basic !time command:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
[time]
<nowiki>!</nowiki>time - This command just prints current time
|}
== Writing plugin code ==

The new-command plugin template that we used to initialize our plugin already defines a new command named "myCommand", so all we have to do is to edit our plugin file ( TimePlugin.pm ) and replace this command by our own "time" command:

First, let's modify the code which sets up the new SPADS command handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addSpadsCommandHandler-handlers-replace-0 addSpadsCommandHandler]. This call is located in the plugin constructor. We edit it so that it becomes:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
[...]
# We declare our new command and the associated handler
addSpadsCommandHandler({time => \&hSpadsTime});
[...]
|}
We must modify the same way the code which removes this SPADS handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#removeSpadsCommandHandler-commands removeSpadsCommandHandler] in the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
[...]
# We remove our new command handler
removeSpadsCommandHandler(['time']);
[...]
|}
Finally, we must replace the handler example "hMyCommand" by our own handler "hSpadsTime". In order to answer to the user issuing the command, we can use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#answer-message answer], which will send an answer message to the user in the same way he sent the command (private message, battle lobby...).

Here is an implementation example for this basic command:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# This is the handler for our new command
sub hSpadsTime {
my ($source,$user,$p_params,$checkOnly)=@_;

# time is a basic command, we have nothing to check in case of callvote
return 1 if($checkOnly);

my @time = localtime();
@time = map(sprintf("%02d",$_),@time);

answer("Current local time: $time[2]:$time[1]:$time[0]");
}
|}

Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/TimePlugin.pm this fully functional TimePlugin] plugin, and its associated [http://planetspads.free.fr/spads/plugins/tutorials/TimePlugin.conf configuration file], [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginCmd.conf command rights configuration file] and [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginHelp.dat command help file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module and the plugin help file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the 2 configuration files in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: "!plugin TimePlugin load". And finally, we can try to say !time in a private message to SPADS or in the battle lobby, and SPADS should answer giving current local time. Our !time command help should also appear in "!help" and "!help time" outputs.

[[Category:SPADS]]

SPADS Inline::Python installation guide

2021-01-28T07:18:25Z

Bibim: Created page with "= Introduction = <code>Inline::Python</code> is a Perl module which allows interactions between Perl code and Python code. SPADS uses it to communicate with plugins coded in..."

= Introduction =

<code>Inline::Python</code> is a Perl module which allows interactions between Perl code and Python code. SPADS uses it to communicate with plugins coded in Python.

Unfortunately the current stable release of this module suffers from a bug which makes Perl strings appear as byte strings when used with Python 3 (Python 2 is unaffected). This is not a blocking problem, as Python can easily convert these data if needed and SPADS plugin API offers dedicated functions to deal with the problem (cf the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#Perl-strings-conversions PYTHON SPECIFIC NOTES - Perl strings conversions] section of the Plugin API documentation). However, a cleaner way to solve this problem is to install a fixed version of the module, directly from the official module maintainer repository. The remaining of this document will detail the different ways to install <code>Inline::Python</code>, on Linux and Windows.

 
= Installing Inline::Python on Linux =
 
== Method 1: Using cpanminus to install latest version from GitHub ==
<code>cpanminus</code> is a lightweight package manager for Perl, which is able to install Perl modules directly from Git repositories. This is very useful for <code>Inline::Python</code> installation because only the latest version from the module maintainer repository includes the fix for Perl string conversions with Python 3.

The first step consists in installing <code>cpanminus</code> (if not already installed on your system). To do that you can usually use the package manager of your Linux distribution. For example, for Debian based distributions: <code>apt-get install cpanminus</code>, or for Red Hat based distributions: <code>dnf install perl-App-cpanminus</code> (for other cases, check [https://metacpan.org/pod/App::cpanminus#INSTALLATION the INSTALLATION section of cpanminus documentation]).

Once <code>cpanminus</code> is installed, it can be used to install the latest version of <code>Inline::Python</code> from module maintainer's repository. This can be done simply by entering following command (with root privileges if you are using the system Perl): 
<code><nowiki>cpanm https://github.com/niner/inline-python-pm.git</nowiki></code>

 
== Method 2: Using the package manager of your Linux distribution ==
This is the easiest way to install <code>Inline::Python</code> (if your distribution supports it), as it automatically downloads and installs a package specifically prepared for your distribution. However, this method installs the stable release of <code>Inline::Python</code>, which suffers from the string conversion bug with Python 3 explained in introduction. So this method is only recommended if you don't plan to use Python 3 or if the installation method based on <code>cpanminus</code> failed.

For this method you just need to find the name of the system package containing the <code>Inline::Python</code> Perl module and install it on your system. 
For example, for Debian based distributions: <code>apt-get install libinline-python-perl</code> 
For Red Hat based distributions: <code>dnf install perl-Inline-Python</code>

 
== Method 3: Using cpan ==
<code>cpan</code> is the standard tool included with Perl to install modules from the [https://www.cpan.org/ Comprehensive Perl Archive Network]. Unfortunately, only the current stable releases of the modules can easily be installed this way, so this method should only be reserved to cases where all other installation methods failed.

To install <code>Inline::Python</code> using <code>cpan</code>, simply enter following command (with root privileges if you are using the system Perl): 
<code>cpan Inline::Python</code>

 
= Installing Inline::Python on Windows =
 
== Method 1: Using cpanminus to install latest version from GitHub ==
<code>cpanminus</code> is a lightweight package manager for Perl, which is able to install Perl modules directly from Git repositories. This is very useful for <code>Inline::Python</code> installation because only the latest version from the module maintainer repository includes the fix for Perl string conversions with Python 3.

If your are using Strawberry Perl, <code>cpanminus</code> should be pre-installed (you can check it by trying the <code>cpanm</code> command in a console windows). If you are using another Perl distribution and <code>cpanminus</code> isn't pre-installed, you should be able to use the packet manager of your Perl distribution (<code>ppm</code> for example for old ActiveState Perl releases) to install <code>cpanminus</code>. You can also use <code>cpan</code> to install it using following command: <code>cpan cpanminus</code>

Once you have checked that <code>cpanminus</code> is installed, you are ready to install the latest version of <code>Inline::Python</code>. Unfortunately, the latest version of <code>Inline::Python</code> on the module maintainer repository has some problems regarding Windows installation. I created my own fork on GitHub to fix these installation problems. As long as the module maintainer didn't merge my fixes in his repository, I recommend using my fork to install the latest version of <code>Inline::Python</code> on Windows, using following command: 
<code><nowiki>cpanm https://github.com/Yaribz/inline-python-pm.git</nowiki></code>

 
== Method 2: Using cpan ==
<code>cpan</code> is the standard tool included with Perl to install modules from the [https://www.cpan.org/ Comprehensive Perl Archive Network]. However, only the current stable releases of the modules can easily be installed this way. As explained in introduction, the current stable release of <code>Inline::Python</code> suffers from the string conversion bug with Python 3, so this method is only recommended if you don't plan to use Python 3 or if the previous installation method based on <code>cpanminus</code> failed.

Unfortunately, the current stable release of <code>Inline::Python</code> doesn't install automatically on Windows due to broken Python libraries detection and one test which is coded for Linux system only and which must be skipped. Consequently, <code>cpan</code> must be run in ineractive mode and with a flag to force installation despite the failing test, using this command: 
<code>cpanm --interactive -f Inline::Python</code>

The install script will then ask 4 questions:
# <code>Use which? [1]</code> Here you must enter the full path of your <code>python.exe</code> file from your Python installation (warning: paths containing spaces are not supported by the installer). For example: <code>C:\Python\python.exe</code>
# <code>Enter extra libraries (e.g. -lfoo -lbar) [None]</code> Here you can press enter, as no additional library should be needed for standard Python installation.
# <code>Which? Or enter another. [1]</code> Here you need to enter the digit corresponding to the library with 2 digits in its name. For example: <code>2</code> (to select entry <code>2) C:/Python/libs/python39.lib</code>)
# <code>Which? Or enter another. [1]</code> Here you can press enter as the install script should have auto-detected the include location of your Python installation correctly.

SPADS

2021-01-28T06:27:27Z

Bibim: /* Development */

SPADS links
----

== Support ==
*[[SPADS:Installation|Installation]]
*[https://springrts.com/phpbb/viewforum.php?f=88 Discussion in Spring forums]
*[http://github.com/Yaribz/SPADS/issues Issue tracker]

== Reference documents ==
*[http://planetspads.free.fr/spads/doc/spadsDoc.html Commands and settings reference guide]
*[http://planetspads.free.fr/spads/conf/templates/ Configuration templates]
*[http://springrts.com/wiki/SPADS_official_plugins_list Official plugins list]
== Memos ==
*[http://springrts.com/wiki/SPADS_update_procedure_for_new_Spring_version SPADS update procedure for new Spring version]
*[http://planetspads.free.fr/spads/repository/UPDATE SPADS manual update procedure for new major SPADS version]
*[http://springrts.com/wiki/SPADS_plugin_install_notes Plugin installation notes]
*[http://springrts.com/wiki/SPADS_PerlUnitSync_module_generation_for_Windows PerlUnitSync module generation for Windows]
== Development ==
*[https://github.com/Yaribz/SPADS Source code]
*[http://planetspads.free.fr/spads/repository/CHANGELOG Detailed changelog]
*[http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html Plugin API documentation]
*[http://springrts.com/wiki/SPADS_plugin_development Plugin development tutorials (Perl)]
*[http://springrts.com/wiki/SPADS_plugin_development_(Python) Plugin development tutorials (Python)]

__NOTOC__
[[Category:Autohosts]]
[[Category:SPADS]]

SPADS plugin development (Python)

2021-01-27T21:11:29Z

Bibim:

= Introduction =

SPADS is an autohost system coded in Perl, it supports both Perl and Python plugins. This tutorial deals with Python plugin development only (for Perl plugin development another tutorial is available [https://springrts.com/wiki/SPADS_plugin_development here]).

SPADS plugins are object-oriented modules. It is strongly recommended to already know Python basics before starting Python plugin development (a Python tutorial is available [https://docs.python.org/3/tutorial/ here]).

= Technical prerequisites =

Python (the Python interpreter and its libraries) must be installed on the system (versions 2.6+ or 3.2+ recommended). The type of installation (32-bit / 64-bit) must be consistent with the Perl version and the Spring engine used for SPADS.

Additionally, in order to allow communication between Perl code (SPADS core) and Python code (SPADS plugins), SPADS uses a Perl module named <code>Inline::Python</code> which must also be installed on the system. The current stable release of this module suffers from a bug which makes Perl strings appear as byte strings when used with Python 3 (Python 2 is unaffected). This is not a blocking problem, as Python can easily convert these data if needed and the plugin API offers dedicated functions to deal with the problem (cf the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#Perl-strings-conversions PYTHON SPECIFIC NOTES - Perl strings conversions] section of the SPADS Plugin API documentation). However, a cleaner way to solve this problem is to install a fixed version of the module, directly from the official module maintainer repository. The remaining of this section will detail the different ways to install the <code>Inline::Python</code> prerequisite, on Linux and on Windows.

== Installing Inline::Python on Linux ==

=== Method 1: Using cpanminus to install latest version from GitHub ===
<code>cpanminus</code> is a lightweight package manager for Perl, which is able to install Perl modules directly from Git repositories. This is very useful for <code>Inline::Python</code> installation because only the latest version from the module maintainer repository includes the fix for Perl string conversions with Python 3.

The first step consists in installing <code>cpanminus</code> (if not already installed on your system). To do that you can usually use the package manager of your Linux distribution. For example, for Debian based distributions: <code>apt-get install cpanminus</code>, for Red Hat based distributions: <code>dnf install perl-App-cpanminus</code> (for other cases, check [https://metacpan.org/pod/App::cpanminus#INSTALLATION the INSTALLATION section of cpanminus documentation]).

Once <code>cpanminus</code> is installed, it can be used to install the latest version of <code>Inline::Python</code> from module maintainer's repository. 
This can be done simply by entering following command (with root privileges if you are using the system Perl): 
<code><nowiki>cpanm https://github.com/niner/inline-python-pm.git</nowiki></code>

=== Method 2: Using the package manager of your Linux distribution ===
This is the easiest way to install <code>Inline::Python</code> (if your distribution supports it), as it automatically downloads and installs a package specifically prepared for your distribution. However, this method installs the stable release of <code>Inline::Python</code>, which suffers from the string conversion bug with Python 3 explained above. So this method is only recommended if you don't plan to use Python 3 or if the installation method based on <code>cpanminus</code> fails.

For this method you just need to find the name of the system package containing the <code>Inline::Python</code> Perl module and install it on your system. 
For example, for Debian based distributions: <code>apt-get install libinline-python-perl</code> 
For Red Hat based distributions: <code>dnf install perl-Inline-Python</code>

=== Method 3: Using cpan ===
<code>cpan</code> is the standard tool included with Perl to install modules from the [https://www.cpan.org/ Comprehensive Perl Archive Network]. Unfortunately, only the current stable releases of the modules can easily be installed this way, so this method should only be reserved to cases where all other installation methods fail.

To install <code>Inline::Python</code> using <code>cpan</code>, simply enter following command (with root privileges if you are using the system Perl): <code>cpan Inline::Python</code>

== Installing Inline::Python on Windows ==

=== Method 1: Using cpanminus to install latest version from GitHub ===
<code>cpanminus</code> is a lightweight package manager for Perl, which is able to install Perl modules directly from Git repositories. This is very useful for <code>Inline::Python</code> installation because only the latest version from the module maintainer repository includes the fix for Perl string conversions with Python 3.

If your are using Strawberry Perl, <code>cpanminus</code> should be pre-installed (you can check it by trying the <code>cpanm</code> command in a console windows). If you are using another Perl distribution and <code>cpanminus</code> isn't pre-installed, you should be able to use the packet manager of your Perl distribution (<code>ppm</code> for example for old ActiveState Perl releases) to install <code>cpanminus</code>. You can also use <code>cpan</code> to install it using following command: <code>cpan cpanminus</code>

Once you have checked that <code>cpanminus</code> is installed, you are ready to install the latest version of <code>Inline::Python</code>. Unfortunately, the latest version of <code>Inline::Python</code> on the module maintainer repository has some problems regarding Windows installation. I created my own fork on GitHub to fix these installation problems. As long as the module maintainer didn't merge my fixes in his repository, I recommend using my fork to install the latest version of <code>Inline::Python</code> on Windows, using following command: 
<code><nowiki>cpanm https://github.com/Yaribz/inline-python-pm.git</nowiki></code>

=== Method 2: Using cpan ===
<code>cpan</code> is the standard tool included with Perl to install modules from the [https://www.cpan.org/ Comprehensive Perl Archive Network]. However, only the current stable releases of the modules can easily be installed this way. As explained above, the current stable release of <code>Inline::Python</code> suffers from the string conversion bug with Python 3, so this method is only recommended if you don't plan to use Python 3 or if the previous installation method based on <code>cpanminus</code> fails.

To install <code>Inline::Python</code> using <code>cpan</code>, simply enter following command: <code>cpan Inline::Python</code>

= 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 [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] (the <code>.pm</code> files must be ignored for this tutorial, these are the Perl versions of the templates).

Our first plugin will be very basic, so we will use the simplest template: <code>mysimpleplugin.py</code>. Let's download [http://planetspads.free.fr/spads/plugins/templates/commented/mysimpleplugin.py 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 <code>HelloWorld</code>. We have to rename the downloaded template from <code>mysimpleplugin.py</code> to <code>helloworld.py</code>, and edit it to replace <code>MySimplePlugin</code> by <code>HelloWorld</code> 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 <code>spads.conf</code> configuration file and reload SPADS configuration).

We have to move our new plugin (<code>helloworld.py</code>) 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): <code>!plugin HelloWorld load</code>. SPADS should answer <code>Loaded plugin HelloWorld.</code>, 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-self-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 <code>onPrivateMsg</code> callback, which will answer <code>Hello World</code> to anyone saying <code>Hello</code> in a private message to SPADS:
<syntaxhighlight lang="python">
# This is the callback called each time SPADS receives a private message
# 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
def onPrivateMsg(self,userName,message):

# Here we "fix" strings received from Perl in case
# the Inline::Python module transmits them as byte strings
(userName,message)=spads.fix_string(userName,message)

# We check the message sent by the user is "Hello"
if message == 'Hello':

# We send our wonderful Hello World message
spads.sayPrivate(userName,'Hello World')

# We return 0 because we don't want to filter out private messages
# for other SPADS processing
return 0</syntaxhighlight>

All we have to do now is adding this callback declaration in our <code>helloworld.py</code> file located in SPADS plugins directory. We obtain [http://planetspads.free.fr/spads/plugins/tutorials/helloworld.py 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: <code>!plugin HelloWorld reload</code>. SPADS should answer <code>Reloaded plugin HelloWorld.</code>, which indicates the plugin has been reloaded successfully.

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

'''/!\ WORK IN PROGRESS /!\'''

= Configurable plugin tutorial (ForbiddenWords) =

In this section we are going to write our first configurable SPADS plugin (a configurable plugin has its own configuration file, named after the plugin name but with ".conf" extension). This plugin will monitor all messages said by players in the battle lobby, and will kick players who use swear words.

== Specifying our configuration parameters ==

The first step of writing a configurable plugin is to choose how we will configure it. In our example, we will use 2 configuration parameters: "words" will contain the list of forbidden words, and "immuneLevel" will contain the minimum autohost access level to be immune regarding these forbidden words checks.

We choose to make "words" a global setting (unmodifiable, not impacted by preset change), and "immuneLevel" a preset setting (modifiable, can be impacted by preset change). The "words" global setting will have no restriction (can be empty, can contain any character...), whereas the "immuneLevel" preset setting will only be allowed to be an integer or integer range.

== Preparing the template ==

Once we have a clear view of our configuration settings, we can start adapting the template for our needs. Since we are making a configurable plugin, this time we will download [http://planetspads.free.fr/spads/plugins/templates/commented/MyConfigurablePlugin.pm the configurable plugin template] and its associated [http://planetspads.free.fr/spads/plugins/templates/commented/MyConfigurablePlugin.conf configuration file example].

First, let's take a look at the configuration file example. This is a just a basic configuration file containing one global setting example and one preset setting example. Let's modify this file to match the configuration we chose as follows (don't forget to rename the file from "MyConfigurablePlugin.conf" to "ForbiddenWords.conf" also):
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# This is our global setting (can't be changed without reloading the configuration)
words:ass;asshole;bastard;bitch;cunt;fuck;motherfucker;shit;whore

# We must define our preset setting in the default preset at least
[default]

# This is our preset setting, which can be changed with "!plugin ... set ..."
# or by loading a preset.
# "100" is the default value, and any integer between 0 and 140 is allowed
immuneLevel:100|0-140
|}
Then we must prepare the plugin template itself, by renaming it from "MyConfigurablePlugin.pm" to "ForbiddenWords.pm" and editing it to replace "MyConfigurablePlugin" by "ForbiddenWords" in the source code. We must also adapt the template so that it uses the configuration settings we chose. This is done by modifying the %globalPluginParams and %presetPluginParam declarations as follows:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# We define one global setting "words" and one preset setting "immuneLevel".
# "words" has no type associated (no restriction on allowed values)
# "immuneLevel" must be an integer or an integer range
# (check %paramTypes hash in SpadsConf.pm for a complete list of allowed
# setting types)
my %globalPluginParams = ( words => [] );
my %presetPluginParams = ( immuneLevel => ['integer','integerRange'] );
|}
== Writing plugin code ==

We want our plugin to react to messages said in the battle lobby. There is no dedicated callback for this event in [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html SPADS plugin API documentation], so we have to set up our own handler on the [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#SAIDBATTLE:server SAIDBATTLE lobby command]. To do so we have to call the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addLobbyCommandHandler-handlers-priority-caller addLobbyCommandHandler]. We will call this function at the end of our plugin constructor as follows, so that it will be set up directly when the plugin is loaded:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
[...]

# We set up a lobby command handler on SAIDBATTLE
addLobbyCommandHandler({SAIDBATTLE => \&hLobbySaidBattle});

# We return the instantiated plugin
return $self;

}
|}
However, if SPADS is disconnected from the lobby due to network problems for example, all lobby handlers are automatically removed. So we must re-add them each time we connect to lobby server. This can be done using the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onLobbyConnected-self-lobbyInterface onLobbyConnected] event-based callback as follows:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# This callback is called each time we (re)connect to the lobby server
sub onLobbyConnected {

# When we are disconnected from the lobby server, all lobby command
# handlers are automatically removed, so we (re)set up our command
# handler here.
addLobbyCommandHandler({SAIDBATTLE => \&hLobbySaidBattle});

}
|}
Also, it is a good practice to remove any handler we have added when the plugin is unloaded. To do so we must implement the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback as follows:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# This callback is called when the plugin is unloaded
sub onUnload {

# We remove our lobby command handler when the plugin is unloaded
removeLobbyCommandHandler(['SAIDBATTLE']);

}
|}
Finally, we have to implement our SAIDBATTLE handler "hLobbySaidBattle". In this handler we need to perform following operations:
* skip processing if the user is the autohost itself: we need to access SPADS configuration to compare the user name with the [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:lobbyLogin lobbyLogin] setting value. So we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getSpadsConf getSpadsConf].
* perform processing according to our configuration ("words" and "immuneLevel" settings): we need to access our plugin configuration, so we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getPluginConf-pluginName-caller getPluginConf].
* retrieve the autohost access level of the user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getUserAccessLevel-user getUserAccessLevel]
* send a message to the battle lobby when we kick someone: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#sayBattle-message sayBattle].
* send a [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#KICKFROMBATTLE:client KICKFROMBATTLE] lobby command to kick a user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#queueLobbyCommand-lobbyCommand queueLobbyCommand].

Here is a commented implementation example of this "hLobbySaidBattle" handler, which will kick any non-privileged user saying a forbidden word in the battle lobby:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# This is the handler we set up on SAIDBATTLE lobby command.
# It is called each time a player says something in the battle lobby.
sub hLobbySaidBattle {

# $command is the lobby command name (SAIDBATTLE)
# $user is the name of the user who said something in the battle lobby
# $message is the message said in the battle lobby
my ($command,$user,$message)=@_;

# First we check it's not a message from SPADS (so we don't kick ourself)
my $p_spadsConf=getSpadsConf();
return if($user eq $p_spadsConf->{lobbyLogin});

# Then we check the user isn't a privileged user
# (autohost access level >= immuneLevel)
my $p_conf=getPluginConf();
return if(getUserAccessLevel($user) >= $p_conf->{immuneLevel});

# We put the forbidden words in a array
my @forbiddenWords=split(/;/,$p_conf->{words});

# We test each forbidden word
foreach my $forbiddenWord (@forbiddenWords) {

# If the message contains the forbidden word (case insensitive)
if($message =~ /\b$forbiddenWord\b/i) {

# Then we kick the user from the battle lobby
sayBattle("Kicking $user from battle (watch your language!)");
queueLobbyCommand(["KICKFROMBATTLE",$user]);

# We quit the foreach loop (no need to test other forbidden word)
last;

}

}

}
|}
Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/ForbiddenWords.pm this fully functional ForbiddenWords] plugin and [http://planetspads.free.fr/spads/plugins/tutorials/ForbiddenWords.conf its associated configuration file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the associated configuration file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: "!plugin ForbiddenWords load". And finally, as an unprivileged user we can try to say some forbidden words in the battle lobby and we should get kicked by the plugin.

= New-command plugin tutorial (TimePlugin) =

In this section we are going to write a plugin which implements a new command for SPADS. Such plugins are configurable plugins like the one we wrote just before, with 2 additional files to configure the new commands. This plugin will give current time when someone types "!time".

== Preparing the template ==

This time we need to download 4 files to prepare our plugin: [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPlugin.pm the new-command plugin template], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPlugin.conf the associated configuration file example], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginHelp.dat the help file example] and [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginCmd.conf the commands rights configuration file example].

As usual, we rename these files to match our plugin name: "MyNewCommandPlugin" --> "TimePlugin". Then we edit the plugin template TimePlugin.pm and replace "MyNewCommandPlugin" by "TimePlugin" in the source code, and we do the same for the plugin configuration template TimePlugin.conf, so that the "commandsFile" and "helpFile" settings are consistent with the files we just renamed.

Then we can edit our command rights requirements configuration file: TimePluginCmd.conf. This file uses the same syntax as the standard SPADS commands.conf file. The template provides a default command "myCommand" with no requirement. We will just rename this command to "time":
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# Anyone can call our command from anywhere
[time]
::|0:
|}
Now we need to write the help information for our new command. This is done in the file TimePluginHelp.dat. This file uses the same syntax as the standard SPADS help.dat file, and the template provides a help example for a command "myCommand" as a syntax reminder. After each command declaration, the first line is the command syntax description, and the other lines are optional usage examples. Let's replace this help example with our own help information for our basic !time command:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
[time]
<nowiki>!</nowiki>time - This command just prints current time
|}
== Writing plugin code ==

The new-command plugin template that we used to initialize our plugin already defines a new command named "myCommand", so all we have to do is to edit our plugin file ( TimePlugin.pm ) and replace this command by our own "time" command:

First, let's modify the code which sets up the new SPADS command handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addSpadsCommandHandler-handlers-replace-0 addSpadsCommandHandler]. This call is located in the plugin constructor. We edit it so that it becomes:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
[...]
# We declare our new command and the associated handler
addSpadsCommandHandler({time => \&hSpadsTime});
[...]
|}
We must modify the same way the code which removes this SPADS handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#removeSpadsCommandHandler-commands removeSpadsCommandHandler] in the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
[...]
# We remove our new command handler
removeSpadsCommandHandler(['time']);
[...]
|}
Finally, we must replace the handler example "hMyCommand" by our own handler "hSpadsTime". In order to answer to the user issuing the command, we can use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#answer-message answer], which will send an answer message to the user in the same way he sent the command (private message, battle lobby...).

Here is an implementation example for this basic command:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# This is the handler for our new command
sub hSpadsTime {
my ($source,$user,$p_params,$checkOnly)=@_;

# time is a basic command, we have nothing to check in case of callvote
return 1 if($checkOnly);

my @time = localtime();
@time = map(sprintf("%02d",$_),@time);

answer("Current local time: $time[2]:$time[1]:$time[0]");
}
|}

Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/TimePlugin.pm this fully functional TimePlugin] plugin, and its associated [http://planetspads.free.fr/spads/plugins/tutorials/TimePlugin.conf configuration file], [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginCmd.conf command rights configuration file] and [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginHelp.dat command help file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module and the plugin help file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the 2 configuration files in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: "!plugin TimePlugin load". And finally, we can try to say !time in a private message to SPADS or in the battle lobby, and SPADS should answer giving current local time. Our !time command help should also appear in "!help" and "!help time" outputs.

[[Category:SPADS]]

SPADS plugin development

2021-01-27T21:07:01Z

Bibim: /* Writing plugin code */

= Introduction =

SPADS is an autohost system coded in Perl, it supports both Perl and Python plugins. This tutorial deals with Perl plugin development only (for Python plugin development another tutorial is available [https://springrts.com/wiki/SPADS_plugin_development_(Python) here]).

SPADS plugins are object-oriented modules. It is strongly recommended to already know Perl basics before starting Perl plugin development (a brief introduction to Perl is available [https://perldoc.perl.org/perlintro here]).

= 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 [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] (the <code>.py</code> files must be ignored for this tutorial, these are the Python versions of the templates).

Our first plugin will be very basic, so we will use the simplest template: <code>MySimplePlugin.pm</code>. 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 <code>HelloWorld</code>. We have to rename the downloaded template from <code>MySimplePlugin.pm</code> to <code>HelloWorld.pm</code>, and edit it to replace <code>MySimplePlugin</code> by <code>HelloWorld</code> 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 <code>spads.conf</code> configuration file and reload SPADS configuration).

We have to move our new plugin (<code>HelloWorld.pm</code>) 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): <code>!plugin HelloWorld load</code>. SPADS should answer <code>Loaded plugin HelloWorld.</code>, 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-self-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 <code>onPrivateMsg</code> callback, which will answer <code>Hello World</code> to anyone saying <code>Hello</code> in a private message to SPADS:
<syntaxhighlight lang="perl">
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;

}</syntaxhighlight>

All we have to do now is adding this callback declaration in our <code>HelloWorld.pm</code> 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: <code>!plugin HelloWorld reload</code>. SPADS should answer <code>Reloaded plugin HelloWorld.</code>, which indicates the plugin has been reloaded successfully.

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

= Configurable plugin tutorial (ForbiddenWords) =

In this section we are going to write our first configurable SPADS plugin (a configurable plugin has its own configuration file, named after the plugin name but with ".conf" extension). This plugin will monitor all messages said by players in the battle lobby, and will kick players who use swear words.

== Specifying our configuration parameters ==

The first step of writing a configurable plugin is to choose how we will configure it. In our example, we will use 2 configuration parameters: "words" will contain the list of forbidden words, and "immuneLevel" will contain the minimum autohost access level to be immune regarding these forbidden words checks.

We choose to make "words" a global setting (unmodifiable, not impacted by preset change), and "immuneLevel" a preset setting (modifiable, can be impacted by preset change). The "words" global setting will have no restriction (can be empty, can contain any character...), whereas the "immuneLevel" preset setting will only be allowed to be an integer or integer range.

== Preparing the template ==

Once we have a clear view of our configuration settings, we can start adapting the template for our needs. Since we are making a configurable plugin, this time we will download [http://planetspads.free.fr/spads/plugins/templates/commented/MyConfigurablePlugin.pm the configurable plugin template] and its associated [http://planetspads.free.fr/spads/plugins/templates/commented/MyConfigurablePlugin.conf configuration file example].

First, let's take a look at the configuration file example. This is a just a basic configuration file containing one global setting example and one preset setting example. Let's modify this file to match the configuration we chose as follows (don't forget to rename the file from "MyConfigurablePlugin.conf" to "ForbiddenWords.conf" also):
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# This is our global setting (can't be changed without reloading the configuration)
words:ass;asshole;bastard;bitch;cunt;fuck;motherfucker;shit;whore

# We must define our preset setting in the default preset at least
[default]

# This is our preset setting, which can be changed with "!plugin ... set ..."
# or by loading a preset.
# "100" is the default value, and any integer between 0 and 140 is allowed
immuneLevel:100|0-140
|}
Then we must prepare the plugin template itself, by renaming it from "MyConfigurablePlugin.pm" to "ForbiddenWords.pm" and editing it to replace "MyConfigurablePlugin" by "ForbiddenWords" in the source code. We must also adapt the template so that it uses the configuration settings we chose. This is done by modifying the %globalPluginParams and %presetPluginParam declarations as follows:
<syntaxhighlight lang="perl">
# We define one global setting "words" and one preset setting "immuneLevel".
# "words" has no type associated (no restriction on allowed values)
# "immuneLevel" must be an integer or an integer range
# (check %paramTypes hash in SpadsConf.pm for a complete list of allowed
# setting types)
my %globalPluginParams = ( words => [] );
my %presetPluginParams = ( immuneLevel => ['integer','integerRange'] );
</syntaxhighlight>

== Writing plugin code ==

We want our plugin to react to messages said in the battle lobby. There is no dedicated callback for this event in [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html SPADS plugin API documentation], so we have to set up our own handler on the [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#SAIDBATTLE:server SAIDBATTLE lobby command]. To do so we have to call the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addLobbyCommandHandler-handlers-priority-caller addLobbyCommandHandler]. We will call this function at the end of our plugin constructor as follows, so that it will be set up directly when the plugin is loaded:
<syntaxhighlight lang="perl">
[...]

# We set up a lobby command handler on SAIDBATTLE
addLobbyCommandHandler({SAIDBATTLE => \&hLobbySaidBattle});

# We return the instantiated plugin
return $self;

}
</syntaxhighlight>
However, if SPADS is disconnected from the lobby due to network problems for example, all lobby handlers are automatically removed. So we must re-add them each time we connect to lobby server. This can be done using the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onLobbyConnected-self-lobbyInterface onLobbyConnected] event-based callback as follows:
<syntaxhighlight lang="perl">
# This callback is called each time we (re)connect to the lobby server
sub onLobbyConnected {

# When we are disconnected from the lobby server, all lobby command
# handlers are automatically removed, so we (re)set up our command
# handler here.
addLobbyCommandHandler({SAIDBATTLE => \&hLobbySaidBattle});

}
</syntaxhighlight>
Also, it is a good practice to remove any handler we have added when the plugin is unloaded. To do so we must implement the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback as follows:
<syntaxhighlight lang="perl">
# This callback is called when the plugin is unloaded
sub onUnload {

# We remove our lobby command handler when the plugin is unloaded
removeLobbyCommandHandler(['SAIDBATTLE']);

}
</syntaxhighlight>
Finally, we have to implement our SAIDBATTLE handler "hLobbySaidBattle". In this handler we need to perform following operations:
* skip processing if the user is the autohost itself: we need to access SPADS configuration to compare the user name with the [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:lobbyLogin lobbyLogin] setting value. So we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getSpadsConf getSpadsConf].
* perform processing according to our configuration ("words" and "immuneLevel" settings): we need to access our plugin configuration, so we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getPluginConf-pluginName-caller getPluginConf].
* retrieve the autohost access level of the user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getUserAccessLevel-user getUserAccessLevel]
* send a message to the battle lobby when we kick someone: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#sayBattle-message sayBattle].
* send a [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#KICKFROMBATTLE:client KICKFROMBATTLE] lobby command to kick a user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#queueLobbyCommand-lobbyCommand queueLobbyCommand].

Here is a commented implementation example of this "hLobbySaidBattle" handler, which will kick any non-privileged user saying a forbidden word in the battle lobby:
<syntaxhighlight lang="perl">
# This is the handler we set up on SAIDBATTLE lobby command.
# It is called each time a player says something in the battle lobby.
sub hLobbySaidBattle {

# $command is the lobby command name (SAIDBATTLE)
# $user is the name of the user who said something in the battle lobby
# $message is the message said in the battle lobby
my ($command,$user,$message)=@_;

# First we check it's not a message from SPADS (so we don't kick ourself)
my $p_spadsConf=getSpadsConf();
return if($user eq $p_spadsConf->{lobbyLogin});

# Then we check the user isn't a privileged user
# (autohost access level >= immuneLevel)
my $p_conf=getPluginConf();
return if(getUserAccessLevel($user) >= $p_conf->{immuneLevel});

# We put the forbidden words in a array
my @forbiddenWords=split(/;/,$p_conf->{words});

# We test each forbidden word
foreach my $forbiddenWord (@forbiddenWords) {

# If the message contains the forbidden word (case insensitive)
if($message =~ /\b$forbiddenWord\b/i) {

# Then we kick the user from the battle lobby
sayBattle("Kicking $user from battle (watch your language!)");
queueLobbyCommand(["KICKFROMBATTLE",$user]);

# We quit the foreach loop (no need to test other forbidden word)
last;

}

}

}
</syntaxhighlight>
Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/ForbiddenWords.pm this fully functional ForbiddenWords] plugin and [http://planetspads.free.fr/spads/plugins/tutorials/ForbiddenWords.conf its associated configuration file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the associated configuration file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: "!plugin ForbiddenWords load". And finally, as an unprivileged user we can try to say some forbidden words in the battle lobby and we should get kicked by the plugin.

= New-command plugin tutorial (TimePlugin) =

In this section we are going to write a plugin which implements a new command for SPADS. Such plugins are configurable plugins like the one we wrote just before, with 2 additional files to configure the new commands. This plugin will give current time when someone types "!time".

== Preparing the template ==

This time we need to download 4 files to prepare our plugin: [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPlugin.pm the new-command plugin template], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPlugin.conf the associated configuration file example], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginHelp.dat the help file example] and [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginCmd.conf the commands rights configuration file example].

As usual, we rename these files to match our plugin name: "MyNewCommandPlugin" --> "TimePlugin". Then we edit the plugin template TimePlugin.pm and replace "MyNewCommandPlugin" by "TimePlugin" in the source code, and we do the same for the plugin configuration template TimePlugin.conf, so that the "commandsFile" and "helpFile" settings are consistent with the files we just renamed.

Then we can edit our command rights requirements configuration file: TimePluginCmd.conf. This file uses the same syntax as the standard SPADS commands.conf file. The template provides a default command "myCommand" with no requirement. We will just rename this command to "time":
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# Anyone can call our command from anywhere
[time]
::|0:
|}
Now we need to write the help information for our new command. This is done in the file TimePluginHelp.dat. This file uses the same syntax as the standard SPADS help.dat file, and the template provides a help example for a command "myCommand" as a syntax reminder. After each command declaration, the first line is the command syntax description, and the other lines are optional usage examples. Let's replace this help example with our own help information for our basic !time command:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
[time]
<nowiki>!</nowiki>time - This command just prints current time
|}
== Writing plugin code ==

The new-command plugin template that we used to initialize our plugin already defines a new command named "myCommand", so all we have to do is to edit our plugin file ( TimePlugin.pm ) and replace this command by our own "time" command:

First, let's modify the code which sets up the new SPADS command handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addSpadsCommandHandler-handlers-replace-0 addSpadsCommandHandler]. This call is located in the plugin constructor. We edit it so that it becomes:
<syntaxhighlight lang="perl">
[...]
# We declare our new command and the associated handler
addSpadsCommandHandler({time => \&hSpadsTime});
[...]
</syntaxhighlight>
We must modify the same way the code which removes this SPADS handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#removeSpadsCommandHandler-commands removeSpadsCommandHandler] in the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback:
<syntaxhighlight lang="perl">
[...]
# We remove our new command handler
removeSpadsCommandHandler(['time']);
[...]
</syntaxhighlight>
Finally, we must replace the handler example "hMyCommand" by our own handler "hSpadsTime". In order to answer to the user issuing the command, we can use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#answer-message answer], which will send an answer message to the user in the same way he sent the command (private message, battle lobby...).

Here is an implementation example for this basic command:
<syntaxhighlight lang="perl">
# This is the handler for our new command
sub hSpadsTime {
my ($source,$user,$p_params,$checkOnly)=@_;

# time is a basic command, we have nothing to check in case of callvote
return 1 if($checkOnly);

my @time = localtime();
@time = map(sprintf("%02d",$_),@time);

answer("Current local time: $time[2]:$time[1]:$time[0]");
}
</syntaxhighlight>

Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/TimePlugin.pm this fully functional TimePlugin] plugin, and its associated [http://planetspads.free.fr/spads/plugins/tutorials/TimePlugin.conf configuration file], [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginCmd.conf command rights configuration file] and [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginHelp.dat command help file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module and the plugin help file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the 2 configuration files in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: "!plugin TimePlugin load". And finally, we can try to say !time in a private message to SPADS or in the battle lobby, and SPADS should answer giving current local time. Our !time command help should also appear in "!help" and "!help time" outputs.

[[Category:SPADS]]

SPADS plugin development (Python)

2021-01-27T21:06:45Z

Bibim: /* Writing plugin code */

'''/!\ IN PROGRESS /!\'''

= Introduction =

SPADS is an autohost system coded in Perl, it supports both Perl and Python plugins. This tutorial deals with Python plugin development only (for Perl plugin development another tutorial is available [https://springrts.com/wiki/SPADS_plugin_development here]).

SPADS plugins are object-oriented modules. It is strongly recommended to already know Python basics before starting Python plugin development (a Python tutorial is available [https://docs.python.org/3/tutorial/ here]).

= Technical prerequisites =

Python (the Python interpreter and its libraries) must be installed on the system (versions 2.6+ or 3.2+ recommended). The type of installation (32-bit / 64-bit) must be consistent with the Perl version and the Spring engine used for SPADS.

Additionally, in order to allow communication between Perl code (SPADS core) and Python code (SPADS plugins), SPADS uses a Perl module named <code>Inline::Python</code> which must also be installed on the system. The current stable release of this module suffers from a bug which makes Perl strings appear as byte strings when used with Python 3 (Python 2 is unaffected). This is not a blocking problem, as Python can easily convert these data if needed and the plugin API offers dedicated functions to deal with the problem (cf the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#Perl-strings-conversions PYTHON SPECIFIC NOTES - Perl strings conversions] section of the SPADS Plugin API documentation). However, a cleaner way to solve this problem is to install a fixed version of the module, directly from the official module maintainer repository. The remaining of this section will detail the different ways to install the <code>Inline::Python</code> prerequisite, on Linux and on Windows.

== Installing Inline::Python on Linux ==

=== Method 1: Using cpanminus to install latest version from GitHub ===
<code>cpanminus</code> is a lightweight package manager for Perl, which is able to install Perl modules directly from Git repositories. This is very useful for <code>Inline::Python</code> installation because only the latest version from the module maintainer repository includes the fix for Perl string conversions with Python 3.

The first step consists in installing <code>cpanminus</code> (if not already installed on your system). To do that you can usually use the package manager of your Linux distribution. For example, for Debian based distributions: <code>apt-get install cpanminus</code>, for Red Hat based distributions: <code>dnf install perl-App-cpanminus</code> (for other cases, check [https://metacpan.org/pod/App::cpanminus#INSTALLATION the INSTALLATION section of cpanminus documentation]).

Once <code>cpanminus</code> is installed, it can be used to install the latest version of <code>Inline::Python</code> from module maintainer's repository. 
This can be done simply by entering following command (with root privileges if you are using the system Perl): 
<code><nowiki>cpanm https://github.com/niner/inline-python-pm.git</nowiki></code>

=== Method 2: Using the package manager of your Linux distribution ===
This is the easiest way to install <code>Inline::Python</code> (if your distribution supports it), as it automatically downloads and installs a package specifically prepared for your distribution. However, this method installs the stable release of <code>Inline::Python</code>, which suffers from the string conversion bug with Python 3 explained above. So this method is only recommended if you don't plan to use Python 3 or if the installation method based on <code>cpanminus</code> fails.

For this method you just need to find the name of the system package containing the <code>Inline::Python</code> Perl module and install it on your system. 
For example, for Debian based distributions: <code>apt-get install libinline-python-perl</code> 
For Red Hat based distributions: <code>dnf install perl-Inline-Python</code>

=== Method 3: Using cpan ===
<code>cpan</code> is the standard tool included with Perl to install modules from the [https://www.cpan.org/ Comprehensive Perl Archive Network]. Unfortunately, only the current stable releases of the modules can easily be installed this way, so this method should only be reserved to cases where all other installation methods fail.

To install <code>Inline::Python</code> using <code>cpan</code>, simply enter following command (with root privileges if you are using the system Perl): <code>cpan Inline::Python</code>

== Installing Inline::Python on Windows ==

=== Method 1: Using cpanminus to install latest version from GitHub ===
<code>cpanminus</code> is a lightweight package manager for Perl, which is able to install Perl modules directly from Git repositories. This is very useful for <code>Inline::Python</code> installation because only the latest version from the module maintainer repository includes the fix for Perl string conversions with Python 3.

If your are using Strawberry Perl, <code>cpanminus</code> should be pre-installed (you can check it by trying the <code>cpanm</code> command in a console windows). If you are using another Perl distribution and <code>cpanminus</code> isn't pre-installed, you should be able to use the packet manager of your Perl distribution (<code>ppm</code> for example for old ActiveState Perl releases) to install <code>cpanminus</code>. You can also use <code>cpan</code> to install it using following command: <code>cpan cpanminus</code>

Once you have checked that <code>cpanminus</code> is installed, you are ready to install the latest version of <code>Inline::Python</code>. Unfortunately, the latest version of <code>Inline::Python</code> on the module maintainer repository has some problems regarding Windows installation. I created my own fork on GitHub to fix these installation problems. As long as the module maintainer didn't merge my fixes in his repository, I recommend using my fork to install the latest version of <code>Inline::Python</code> on Windows, using following command: 
<code><nowiki>cpanm https://github.com/Yaribz/inline-python-pm.git</nowiki></code>

=== Method 2: Using cpan ===
<code>cpan</code> is the standard tool included with Perl to install modules from the [https://www.cpan.org/ Comprehensive Perl Archive Network]. However, only the current stable releases of the modules can easily be installed this way. As explained above, the current stable release of <code>Inline::Python</code> suffers from the string conversion bug with Python 3, so this method is only recommended if you don't plan to use Python 3 or if the previous installation method based on <code>cpanminus</code> fails.

To install <code>Inline::Python</code> using <code>cpan</code>, simply enter following command: <code>cpan Inline::Python</code>

= 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 [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] (the <code>.pm</code> files must be ignored for this tutorial, these are the Perl versions of the templates).

Our first plugin will be very basic, so we will use the simplest template: <code>mysimpleplugin.py</code>. Let's download [http://planetspads.free.fr/spads/plugins/templates/commented/mysimpleplugin.py 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 <code>HelloWorld</code>. We have to rename the downloaded template from <code>mysimpleplugin.py</code> to <code>helloworld.py</code>, and edit it to replace <code>MySimplePlugin</code> by <code>HelloWorld</code> 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 <code>spads.conf</code> configuration file and reload SPADS configuration).

We have to move our new plugin (<code>helloworld.py</code>) 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): <code>!plugin HelloWorld load</code>. SPADS should answer <code>Loaded plugin HelloWorld.</code>, 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-self-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 <code>onPrivateMsg</code> callback, which will answer <code>Hello World</code> to anyone saying <code>Hello</code> in a private message to SPADS:
<syntaxhighlight lang="python">
# This is the callback called each time SPADS receives a private message
# 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
def onPrivateMsg(self,userName,message):

# Here we "fix" strings received from Perl in case
# the Inline::Python module transmits them as byte strings
(userName,message)=spads.fix_string(userName,message)

# We check the message sent by the user is "Hello"
if message == 'Hello':

# We send our wonderful Hello World message
spads.sayPrivate(userName,'Hello World')

# We return 0 because we don't want to filter out private messages
# for other SPADS processing
return 0</syntaxhighlight>

All we have to do now is adding this callback declaration in our <code>helloworld.py</code> file located in SPADS plugins directory. We obtain [http://planetspads.free.fr/spads/plugins/tutorials/helloworld.py 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: <code>!plugin HelloWorld reload</code>. SPADS should answer <code>Reloaded plugin HelloWorld.</code>, which indicates the plugin has been reloaded successfully.

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

= Configurable plugin tutorial (ForbiddenWords) =

In this section we are going to write our first configurable SPADS plugin (a configurable plugin has its own configuration file, named after the plugin name but with ".conf" extension). This plugin will monitor all messages said by players in the battle lobby, and will kick players who use swear words.

== Specifying our configuration parameters ==

The first step of writing a configurable plugin is to choose how we will configure it. In our example, we will use 2 configuration parameters: "words" will contain the list of forbidden words, and "immuneLevel" will contain the minimum autohost access level to be immune regarding these forbidden words checks.

We choose to make "words" a global setting (unmodifiable, not impacted by preset change), and "immuneLevel" a preset setting (modifiable, can be impacted by preset change). The "words" global setting will have no restriction (can be empty, can contain any character...), whereas the "immuneLevel" preset setting will only be allowed to be an integer or integer range.

== Preparing the template ==

Once we have a clear view of our configuration settings, we can start adapting the template for our needs. Since we are making a configurable plugin, this time we will download [http://planetspads.free.fr/spads/plugins/templates/commented/MyConfigurablePlugin.pm the configurable plugin template] and its associated [http://planetspads.free.fr/spads/plugins/templates/commented/MyConfigurablePlugin.conf configuration file example].

First, let's take a look at the configuration file example. This is a just a basic configuration file containing one global setting example and one preset setting example. Let's modify this file to match the configuration we chose as follows (don't forget to rename the file from "MyConfigurablePlugin.conf" to "ForbiddenWords.conf" also):
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# This is our global setting (can't be changed without reloading the configuration)
words:ass;asshole;bastard;bitch;cunt;fuck;motherfucker;shit;whore

# We must define our preset setting in the default preset at least
[default]

# This is our preset setting, which can be changed with "!plugin ... set ..."
# or by loading a preset.
# "100" is the default value, and any integer between 0 and 140 is allowed
immuneLevel:100|0-140
|}
Then we must prepare the plugin template itself, by renaming it from "MyConfigurablePlugin.pm" to "ForbiddenWords.pm" and editing it to replace "MyConfigurablePlugin" by "ForbiddenWords" in the source code. We must also adapt the template so that it uses the configuration settings we chose. This is done by modifying the %globalPluginParams and %presetPluginParam declarations as follows:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# We define one global setting "words" and one preset setting "immuneLevel".
# "words" has no type associated (no restriction on allowed values)
# "immuneLevel" must be an integer or an integer range
# (check %paramTypes hash in SpadsConf.pm for a complete list of allowed
# setting types)
my %globalPluginParams = ( words => [] );
my %presetPluginParams = ( immuneLevel => ['integer','integerRange'] );
|}
== Writing plugin code ==

We want our plugin to react to messages said in the battle lobby. There is no dedicated callback for this event in [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html SPADS plugin API documentation], so we have to set up our own handler on the [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#SAIDBATTLE:server SAIDBATTLE lobby command]. To do so we have to call the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addLobbyCommandHandler-handlers-priority-caller addLobbyCommandHandler]. We will call this function at the end of our plugin constructor as follows, so that it will be set up directly when the plugin is loaded:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
[...]

# We set up a lobby command handler on SAIDBATTLE
addLobbyCommandHandler({SAIDBATTLE => \&hLobbySaidBattle});

# We return the instantiated plugin
return $self;

}
|}
However, if SPADS is disconnected from the lobby due to network problems for example, all lobby handlers are automatically removed. So we must re-add them each time we connect to lobby server. This can be done using the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onLobbyConnected-self-lobbyInterface onLobbyConnected] event-based callback as follows:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# This callback is called each time we (re)connect to the lobby server
sub onLobbyConnected {

# When we are disconnected from the lobby server, all lobby command
# handlers are automatically removed, so we (re)set up our command
# handler here.
addLobbyCommandHandler({SAIDBATTLE => \&hLobbySaidBattle});

}
|}
Also, it is a good practice to remove any handler we have added when the plugin is unloaded. To do so we must implement the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback as follows:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# This callback is called when the plugin is unloaded
sub onUnload {

# We remove our lobby command handler when the plugin is unloaded
removeLobbyCommandHandler(['SAIDBATTLE']);

}
|}
Finally, we have to implement our SAIDBATTLE handler "hLobbySaidBattle". In this handler we need to perform following operations:
* skip processing if the user is the autohost itself: we need to access SPADS configuration to compare the user name with the [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:lobbyLogin lobbyLogin] setting value. So we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getSpadsConf getSpadsConf].
* perform processing according to our configuration ("words" and "immuneLevel" settings): we need to access our plugin configuration, so we will need the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getPluginConf-pluginName-caller getPluginConf].
* retrieve the autohost access level of the user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#getUserAccessLevel-user getUserAccessLevel]
* send a message to the battle lobby when we kick someone: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#sayBattle-message sayBattle].
* send a [http://springrts.com/dl/LobbyProtocol/ProtocolDescription.html#KICKFROMBATTLE:client KICKFROMBATTLE] lobby command to kick a user: we will use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#queueLobbyCommand-lobbyCommand queueLobbyCommand].

Here is a commented implementation example of this "hLobbySaidBattle" handler, which will kick any non-privileged user saying a forbidden word in the battle lobby:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# This is the handler we set up on SAIDBATTLE lobby command.
# It is called each time a player says something in the battle lobby.
sub hLobbySaidBattle {

# $command is the lobby command name (SAIDBATTLE)
# $user is the name of the user who said something in the battle lobby
# $message is the message said in the battle lobby
my ($command,$user,$message)=@_;

# First we check it's not a message from SPADS (so we don't kick ourself)
my $p_spadsConf=getSpadsConf();
return if($user eq $p_spadsConf->{lobbyLogin});

# Then we check the user isn't a privileged user
# (autohost access level >= immuneLevel)
my $p_conf=getPluginConf();
return if(getUserAccessLevel($user) >= $p_conf->{immuneLevel});

# We put the forbidden words in a array
my @forbiddenWords=split(/;/,$p_conf->{words});

# We test each forbidden word
foreach my $forbiddenWord (@forbiddenWords) {

# If the message contains the forbidden word (case insensitive)
if($message =~ /\b$forbiddenWord\b/i) {

# Then we kick the user from the battle lobby
sayBattle("Kicking $user from battle (watch your language!)");
queueLobbyCommand(["KICKFROMBATTLE",$user]);

# We quit the foreach loop (no need to test other forbidden word)
last;

}

}

}
|}
Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/ForbiddenWords.pm this fully functional ForbiddenWords] plugin and [http://planetspads.free.fr/spads/plugins/tutorials/ForbiddenWords.conf its associated configuration file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the associated configuration file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: "!plugin ForbiddenWords load". And finally, as an unprivileged user we can try to say some forbidden words in the battle lobby and we should get kicked by the plugin.

= New-command plugin tutorial (TimePlugin) =

In this section we are going to write a plugin which implements a new command for SPADS. Such plugins are configurable plugins like the one we wrote just before, with 2 additional files to configure the new commands. This plugin will give current time when someone types "!time".

== Preparing the template ==

This time we need to download 4 files to prepare our plugin: [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPlugin.pm the new-command plugin template], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPlugin.conf the associated configuration file example], [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginHelp.dat the help file example] and [http://planetspads.free.fr/spads/plugins/templates/commented/MyNewCommandPluginCmd.conf the commands rights configuration file example].

As usual, we rename these files to match our plugin name: "MyNewCommandPlugin" --> "TimePlugin". Then we edit the plugin template TimePlugin.pm and replace "MyNewCommandPlugin" by "TimePlugin" in the source code, and we do the same for the plugin configuration template TimePlugin.conf, so that the "commandsFile" and "helpFile" settings are consistent with the files we just renamed.

Then we can edit our command rights requirements configuration file: TimePluginCmd.conf. This file uses the same syntax as the standard SPADS commands.conf file. The template provides a default command "myCommand" with no requirement. We will just rename this command to "time":
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# Anyone can call our command from anywhere
[time]
::|0:
|}
Now we need to write the help information for our new command. This is done in the file TimePluginHelp.dat. This file uses the same syntax as the standard SPADS help.dat file, and the template provides a help example for a command "myCommand" as a syntax reminder. After each command declaration, the first line is the command syntax description, and the other lines are optional usage examples. Let's replace this help example with our own help information for our basic !time command:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
[time]
<nowiki>!</nowiki>time - This command just prints current time
|}
== Writing plugin code ==

The new-command plugin template that we used to initialize our plugin already defines a new command named "myCommand", so all we have to do is to edit our plugin file ( TimePlugin.pm ) and replace this command by our own "time" command:

First, let's modify the code which sets up the new SPADS command handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#addSpadsCommandHandler-handlers-replace-0 addSpadsCommandHandler]. This call is located in the plugin constructor. We edit it so that it becomes:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
[...]
# We declare our new command and the associated handler
addSpadsCommandHandler({time => \&hSpadsTime});
[...]
|}
We must modify the same way the code which removes this SPADS handler using the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#removeSpadsCommandHandler-commands removeSpadsCommandHandler] in the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onUnload-self-context onUnload] event-based callback:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
[...]
# We remove our new command handler
removeSpadsCommandHandler(['time']);
[...]
|}
Finally, we must replace the handler example "hMyCommand" by our own handler "hSpadsTime". In order to answer to the user issuing the command, we can use the plugin API function [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#answer-message answer], which will send an answer message to the user in the same way he sent the command (private message, battle lobby...).

Here is an implementation example for this basic command:
{|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" |
|
# This is the handler for our new command
sub hSpadsTime {
my ($source,$user,$p_params,$checkOnly)=@_;

# time is a basic command, we have nothing to check in case of callvote
return 1 if($checkOnly);

my @time = localtime();
@time = map(sprintf("%02d",$_),@time);

answer("Current local time: $time[2]:$time[1]:$time[0]");
}
|}

Once we put all that together, we obtain [http://planetspads.free.fr/spads/plugins/tutorials/TimePlugin.pm this fully functional TimePlugin] plugin, and its associated [http://planetspads.free.fr/spads/plugins/tutorials/TimePlugin.conf configuration file], [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginCmd.conf command rights configuration file] and [http://planetspads.free.fr/spads/plugins/tutorials/TimePluginHelp.dat command help file].

== Testing our plugin ==

To test our plugin, we have to put the plugin module and the plugin help file in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:pluginsDir SPADS plugins directory], and the 2 configuration files in [http://planetspads.free.fr/spads/doc/spadsDoc_All.html#global:etcDir SPADS etc directory].

Then we load the plugin as follows: "!plugin TimePlugin load". And finally, we can try to say !time in a private message to SPADS or in the battle lobby, and SPADS should answer giving current local time. Our !time command help should also appear in "!help" and "!help time" outputs.

[[Category:SPADS]]