SPADS plugin development (Python) - Revision history

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)]"

2024-07-15T10:08:22Z

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

Show changes

Bibim at 14:24, 28 January 2021

2021-01-28T14:24:25Z

← Older revision		Revision as of 15:24, 28 January 2021
Line 203:		Line 203:

	<br>		<br>

	~~<span style="color:#ff0000">'''/!\ WORK IN PROGRESS /!\'''</span>~~

	= New-command plugin tutorial (TimePlugin) =		= New-command plugin tutorial (TimePlugin) =
Line 270:		Line 268:
	</syntaxhighlight>		</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].		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].

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

2021-01-28T14:22:39Z

New-command plugin tutorial (TimePlugin)

← Older revision		Revision as of 15:22, 28 January 2021
Line 254:		Line 254:
	# This is the handler for our new command		# This is the handler for our new command
	def hSpadsTime(source,user,params,checkOnly):		def hSpadsTime(source,user,params,checkOnly):

	# time is a basic command, we have nothing to check in case of callvote		# checkOnly is true if this is just a check for callVote command, not a real command execution
	return 1 ~~if($checkOnly);~~		if checkOnly :

	~~my @time~~ = ~~localtime~~();		# time is a basic command, we have nothing to check in case of callvote
	~~@time~~ = ~~map(sprintf~~("%~~02d~~",~~$_)~~,~~@time~~);		return 1

	answer("Current local time: ~~$time[2]:$time[1]:$time[0]~~");		# 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>		</syntaxhighlight>

Bibim: /* Writing plugin code */

2021-01-28T13:24:02Z

Writing plugin code

← Older revision		Revision as of 14:24, 28 January 2021
Line 236:		Line 236:
	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:		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">		<syntaxhighlight lang="python">
	[...]		[...]
	# We declare our new command and the associated handler		# We declare our new command and the associated handler
	addSpadsCommandHandler({time ~~=> \&~~hSpadsTime});		spads.addSpadsCommandHandler({'time': hSpadsTime})
	[...]		[...]
	</syntaxhighlight>		</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:		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">		<syntaxhighlight lang="python">
	[...]		[...]
	# We remove our new command handler		# We remove our new command handler
	removeSpadsCommandHandler(['time']);		spads.removeSpadsCommandHandler(['time'])
	[...]		[...]
	</syntaxhighlight>		</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...).		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...).
Line 252:		Line 252:
	Here is an implementation example for this basic command:		Here is an implementation example for this basic command:
	<syntaxhighlight lang="python">		<syntaxhighlight lang="python">
	# This is the handler for our new command		# This is the handler for our new command
	~~sub~~ hSpadsTime {		def hSpadsTime(source,user,params,checkOnly):
	my ($source,$user,~~$p_params~~,$checkOnly)~~=@_;~~

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

Bibim: /* Preparing the template */

2021-01-28T13:20:50Z

Preparing the template

← Older revision		Revision as of 14:20, 28 January 2021
Line 219:		Line 219:
	{\|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" \|		{\|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" \|
	\|		\|
	# Anyone can call our command from anywhere		# Anyone can call our command from anywhere
	[time]		[time]
	::\|0:		::\|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:		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" \|		{\|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" \|
	\|		\|
	[time]		[time]
	<nowiki>!</nowiki>time - This command just prints current time		<nowiki>!</nowiki>time - This command just prints current time
	\|}		\|}

	== Writing plugin code ==		== Writing plugin code ==

Bibim at 13:13, 28 January 2021

2021-01-28T13:13:01Z

← Older revision		Revision as of 14:13, 28 January 2021
Line 73:		Line 73:

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

	~~<span style="color:#ff0000">'''/!\ WORK IN PROGRESS /!\'''</span>~~

	<br>		<br>
Line 205:		Line 203:

	<br>		<br>

			<span style="color:#ff0000">'''/!\ WORK IN PROGRESS /!\'''</span>

	= New-command plugin tutorial (TimePlugin) =		= New-command plugin tutorial (TimePlugin) =

Bibim: /* Writing plugin code */

2021-01-28T13:10:44Z

Writing plugin code

Show changes

Bibim: /* Preparing the template */

2021-01-28T12:35:45Z

Preparing the template

← Older revision		Revision as of 13:35, 28 January 2021
Line 94:		Line 94:
	{\|style="margin-top: 10px; margin-left: 40px; background-color: #38474E; border: 1px solid black; border-color: #20292E" \|		{\|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)		# This is our global setting (can't be changed without reloading the configuration)
	words:ass;asshole;bastard;bitch;cunt;fuck;motherfucker;shit;whore		words:ass;asshole;bastard;bitch;cunt;fuck;motherfucker;shit;whore

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

	# This is our preset setting, which can be changed with "!plugin ... set ..."		# This is our preset setting, which can be changed with "!plugin ... set ..."
	# or by loading a preset.		# or by loading a preset.
	# "100" is the default value, and any integer between 0 and 140 is allowed		# "100" is the default value, and any integer between 0 and 140 is allowed
	immuneLevel:100\|0-140		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:		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:

Bibim: /* Writing plugin code */

2021-01-28T11:33:09Z

Writing plugin code

← Older revision		Revision as of 12:33, 28 January 2021
Line 200:		Line 200:

	}		}
			</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>		</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].		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].

Bibim: /* Preparing the template */

2021-01-28T11:14:08Z

Preparing the template

← Older revision		Revision as of 12:14, 28 January 2021
Line 112:		Line 112:
	# (check %paramTypes hash in SpadsConf.pm for a complete list of allowed		# (check %paramTypes hash in SpadsConf.pm for a complete list of allowed
	# setting types)		# setting types)
	~~my %~~globalPluginParams = ( words => [] );		globalPluginParams = { 'words': [] }
	~~my %~~presetPluginParams = ( immuneLevel => ['integer','integerRange'] );		presetPluginParams = { 'immuneLevel': ['integer','integerRange'] }
	</syntaxhighlight>		</syntaxhighlight>